This article describes the process for adding content to the Javadocs so that they show up in the overview-summary.html file.


The Javadocs are maintain in the juneau-doc project.

We maintain all of our documentation (other than the website itself) inside the overview document of the Javadocs.  

For example:

The advantage is that you can easily link to class-level javadocs anywhere in the documentation.  And we could maintain versions of the documentation.

For a while we maintained a single overview.html file.  As the documentation grew, it became impossible to maintain the single file (Eclipse would struggle trying to load the file).  Therefore, the file was broken up into smaller pieces that could be combined into an overview.html file before running the maven command to generate the docs. 


The pieces of the overview document are stored in the docs directory:

Release notes are stored in the ReleaseNotes folder.  Whenever there is a new release, create a new one of these files.  The format is pretty straight-forward:

Topics are stored in the Topics folder.  You'll notice that subtopics are stored in folders whose name match the file name:

Topics can be nested up to 3 levels deep.

The format of each topic file consists of the copyright statement, then a single line representing the topic title, and then arbitrary HTML:

You can also add any of the following tags at the beginning of the topic title to represent modifications:  "{new}","{updated}","{todo}".
For example:

juneau-build-javadoc launcher

The juneau-build-javadoc launcher is then used to construct the overview.html file:

The launcher does the following:

  1. Runs the DocGenerator class found in the juneau-doc project. 
    Here's what it does:
    1. Renames the file and directory names of the topics so that they're in sequential order.  So for example, if you want to add a new topic file, just add it with a number close to where you want it inserted and it will insert it for you. 
    2. Generates the Table of Contents section.  
    3. Generates the contents of the docs.txt file.  This allows you to insert topic links in your HTML through the use of doc taglets described below.
    4. Replaces strings (to simplify "{@link xxx}" tags):
      1. "oaj"→"org.apache.juneau"
      2. "oajr"→""
      3. "oajrc"→""
    5. Constructs the contents of overview.html using the template file overview-template.html
  2. Runs "mvn javadoc:aggregate" to build the javadocs.
  3. Runs DocLinkTester class which checks all the generated javadocs for any broken links (e.g. missing images, etc...).
  4. Copies the generated Javadocs to the /juneau-website/content/site/apidocs-$JUNEAU_VERSION folder so that they're ready to upload to the website.


Two custom taglet classes are provided for you:

  • "{@doc xxx}" - Allows you to reference topics by name instead of having to construct hyperlinks yourself.
  • "{@property xxx}" - Allows you to reference system properties.  
    Two system properties are passed in:  juneauVersion and juneauVersionNext.  
    Therefore if you want to insert the juneau version into your HTML, just use "{@property juneauVersion}".
  • "{@fragment xxx}" - Resolves to the contents of a file located in the /juneau-doc/docs/Fragments folder. 

One caveat....resolved fragments cannot contain other tags.  The javadoc tool apparently does not support recursive resolution of tags.