I recently Installed Java 8. The first thing I needed to know was how to get back. If you are using OSX you might be interested in this little tool.
The biggest problem I found so far is not Java itself, but Javadoc. More specifically, doclint. The short of it is you might want to disable it just to get your projects to build. That’s of course assuming you use Javadoc at all. In any case, the incantation is:
-Xdoclint:none
I write specifications and try to get developers to conform to them. This is always a mixed bag. I’ve done my share of compliance testing and prodding along the way. Here’s what pisses people off: checking for something you never cared about before and causing things not under active development to break. Not even a warning for starters.
Much of it is good actually since I’m not that much of a mess.
- no broken references in @param, @return, @throws, @link
- make sure you have @param, @return, and @throws where applicable
- valid HTML
That last one is problematic. It’s not that we all don’t know to close our tags and not put block elements inside inline elements. Javadoc is trying to be compliant with W3C HTML 4.01, sort of. Who still writes HTML4? Apparently Oracle does.
After HTML4, XHTML was the next big thing. Lower case elements, quotes around attributes, validate, validate, and validate. I got used to it. So used to it I never saw what all the fuss between XHTML 2.0 and HTML 5 was about but here’s nothing that gets a specification off the ground faster than the other guy’s specification. Anyway, I embraced HTML 5 although it now looks more anal-retentive than most people’s who didn’t swallow the XML kool-aid. But this is a post about Javadoc…
"self-closing element not allowed"
Apparently, there are different interpretations of self-closing elements in HTML4 such as <br/> and <hr/>. The W3C validator issues warnings but doclint fails hard. I don’t really know and it’s so last millennium. I could go on about the speed bumps in getting inline documentation and enabling any kind of validity checking. I could go on that strict conformance to an obsolete specification isn’t the noble path. My problem is these are freaking everywhere in the OSID docs.
Maybe I should question why on earth there are forced line breaks in there. Maybe in the end it is a good thing to fix the semantics. I don’t have time for this. Bye bye doclint. Now it all looks valid!