JavaDoc source code embeds are pretty terrible!
I love JavaDoc but it didn't age well. When you work with other tools (e.g. in the Microsoft world) suddenly the embedded samples look amazing and "search" functionality is just built in!
Why Can't We Have That?
JDK 9 is introducing new support for search, but source embeds can be so much better and are a crucial learning tool...
Since documentation and proper code samples are so crucial, we decided to revisit our javadocs and start from the ground up, to that point we created the new open source project: JavaDoc Source Embed.
The goal of this project is to allow using Github "gist" in JavaDoc which allows you to create a JavaDoc that looks like this instead of the normally anemic source embeds. If you are unfamiliar with Github gists, it's essentially a code snippet hosting service that both formats the code nicely and allows you to easily maintain it thru Github (fork, star, watch, etc.).
The central hosting is the true "killer feature". It allows you to embed the sample everywhere that's applicable instead of copying and pasting it. For example, the LocationManager is a good place to hold the sample but so is the Geofence class. In those cases we only had to copy this small snippet in the JavaDoc:
We'll try to update our JavaDocs, but would be happy for pull requests and issues pointing at missing samples and where they should be placed in the code.
Developer Guide Wiki
In other news, Codename One just finished the migration of the developer guide to the Github Wiki page and already it looks radically different. The approach of using Github's Wiki pages has its drawbacks and Asciidoc does have some pain points, but overall I think this is a good direction for an open project.
Ismael Baum made a lot of Wiki edits fixing many grammatical and logical errors, picking up so many mistakes in the process!
Besides the many rewrites and fixes we made for the document, we also authored a script that translates Codename One class names to links into the JavaDoc.
So, now instead of just highlighting the mention of
LocationManager, you would see LocationManager which is far more useful. Notice that this shouldn't affect things like code blocks, only mentions of a specific class. From this point on, we'll try to interconnect the documentation to produce a more coherent experience with the docs.
I'd open source the script we used for the links, but it's mostly a bunch of very specific
sed commands which probably won't be useful for anyone. We won't run it again since it's a "one-off" script, we'll just need to keep the linking going.
Do you know of other tools we can use to improve the state of our documentation?
We are looking for several things that still seem to be difficult with the current toolchain:
- Better JavaDoc integrations — ability to embed it into the existing web design would be wonderful! CSS is a bit too limiting.
- Improving the look of the Asciidoc PDF — Currently the PDF looks too academic in the opening page there are some solutions for that but most seem hackish.
- Grammar & style tools — There are some decent grammar checkers for word processors but we couldn't find anything that works with Asciidoc. The same is missing for writing analysis tools that can point out unclear writing. I saw that Gitbooks has some interesting tools there, but I'm unsure whether we want to use them.
Let us know if you are familiar with such tools or something else that we might not be aware of.