Javadoc custom doclets – fun, frustration and forward motion

Javadoc is default - and often only - documentation for open source Java projects. It is generated automatically and can just be dumped on any public-facing server as a bunch of static files. Or even bundled with the distribution, if size is not an issue.

However, as project grows, several issues with using Javadoc documentation become apparent. The main issue is that Javadoc (yes, even JDK 8 one) uses frames and JavaScript for navigating the packages and classes. Which breaks any sort of direct linking to the content as well as discoverability by search engine. Yes, there are NO FRAMES links, but then the navigation becomes really cumbersome. The second issue is that generated Javadoc is using rather old HTML standards and is really not designed for Search Engine Optimization. Which means that search engines usually end up discovering random entry points following somebody’s old blog post.

Checking examples in “Solr Indexing” with Solr 4.7 under Windows – part 1

It’s been 9 months since my introductory Solr book came out. It was written for version 4.3. In the meanwhile, Solr kept marching on and is now at version 4.7. There has been quite a number of changes and new features. So I really wanted to recheck that the examples in the book still make sense.  I also wanted to do the tests on Windows to see whether the *nix-centered instructions in the book caused any issues.

This first part covers the issues and supplementary material based on the review of the first five chapters. Later parts will be covered in other blog posts. So far, it seems that the examples survived without any serious issues.