JavaDoc source code embeds suck!
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 JavaDoc that looks
like this
instead of the normally anemic source embeds.
If you are unfamiliar with github gists its 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. E.g. 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:

<script src="https://gist.github.com/codenameone/b0fa5280bde905a8f0cd.js"></script>

The only two problems with gist are its lack of searchability and the fact that it won’t appear in IDE’s that don’t
render JavaScript. The JavaDoc Source Embed
project effectively solves that by automatically generating a “noscript” tag with the latest version of the gist
so it appears properly everywhere it is referenced.

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 we just finished the migration of the developer guide to the github wiki page and already it looks
radically different. The approach of using githubs 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 its mostly a bunch of very specific sed
commands which probably won’t be useful for anyone. We won’t run it again since its a “one off” script,
we’ll just need to keep the linking going.

Feedback

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 hard 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 it.

Let us know if you are familiar with such tools or something else that we might not be aware of.