JavaDoc Source Embed

JavaDoc is a wonderful tool with some annoying limitations, one of them is its inability to handle source code embeds. Githubs gist is an amazing tool for embeding source code but it requires JavaScript which means it doesn't work with the popups in common IDE's and isn't as searchable.

Gist makes source embedding trivial since you can embed a single sample in multiple methods/classes and manage the sample itself in a centeral location.

Which makes it look like this: https://www.codenameone.com/javadoc/com/codename1/location/LocationManager.html

With JavaScript enabled you see this:

Without JavaScript (or in IDE/search engine) you will see this:

Those screenshots were generated by this javadoc, notice that all the source comes from this gist:

/**
 * <p>The LocationManager is the main entry to retrieveLocation or to bind  a LocationListener, important: in 
 * order to use location on iOS you will need to define the build argument ios.locationUsageDescription.
 * This build argument should be used to describe to Apple &amp; the users why you need to use the location 
 * functionality.</p>
 * 
 * <p>Usage:</p>
 * <script src="https://gist.github.com/codenameone/b0fa5280bde905a8f0cd.js"></script>
 */
public abstract class LocationManager {

When you generate JavaDoc it queries github for the gist contents and embeds it as a <noscript> alternative right into the code. This means IDE code completion will "just work" as it will have a sensible fallback.

Just pass the source directory and an output directory to the jar file and then generate the javadoc based on the output directory.

E.g:

rm -Rf dist/javadoc
rm -Rf build/tempJavaSources
java -jar JavaDocSourceEmbed-1.0-SNAPSHOT.jar pathToSrcDir/src build/tempJavaSources

javadoc -protected -d dist/javadoc -windowtitle "Codename One API" build/tempJavaSources

Important: notice that we use a temporary directory to generate the source and don't generate to the original directory. The reason for that is simple. If you change the gist or add additional gists in the future youd want them to be updated.

Or using ant you can do something like:

<delete dir="temp/javadocsources" />
<java fork="true" jar="JavaDocSourceEmbed-1.0-SNAPSHOT.jar">
    <arg file="src" />
    <arg file="temp/javadocsources" />
</java>
<javadoc author="Me Me Me Me" protected="true" windowtitle="My Great New API"  destdir="javadoc">
    <packageset dir="temp/javadocsources">
    </packageset>            
</javadoc>