You are viewing an old version of this page. View the current version.

Compare with Current View Page History

Version 1 Next »

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

Background

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:  http://juneau.apache.org/site/apidocs-7.2.2/overview-summary.html#TOC

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. 

Overview

The pieces of the overview document are stored in the src/main/resources 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:


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

The launcher runs the DocGenerator class found in the juneau-doc project.  Here's what it does:

  • 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. 
  • Generates the Table of Contents section.  

  • 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.

  • Replaces strings (to simplify "{@link xxx}" tags):
    • "oaj"→"org.apache.juneau"
    • "oajr"→"org.apache.juneau.rest"
    • "oajrc"→"org.apache.juneau.rest.client"

  • Constructs the contents of overview.html using the template file overview-template.html.

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}".





  • No labels