foundation-javadoc

This is an extension to the standard JavaDoc tool, originally built to be used for the documentation of the Foundation Library.

To use the provided extensions in your project, add the following parameters to your JavaDoc call:

-tagletpath /path/to/org.tquadrat.foundation.javadoc-0.1.0.jar:/path/to/apiguardian-api-1.1.2.jar:/path/to/jakarta.activation-2.0.1.jar

-taglet org.tquadrat.foundation.javadoc.AuthorTaglet
-taglet org.tquadrat.foundation.javadoc.AnchorTaglet
-taglet org.tquadrat.foundation.javadoc.HRefTaglet
-taglet org.tquadrat.foundation.javadoc.IgnoreTaglet
-taglet org.tquadrat.foundation.javadoc.IncludeTaglet
-taglet org.tquadrat.foundation.javadoc.InspiredTaglet
-taglet org.tquadrat.foundation.javadoc.ModifiedTaglet
-taglet org.tquadrat.foundation.javadoc.NoteTaglet
-taglet org.tquadrat.foundation.javadoc.ThanksTaglet
-taglet org.tquadrat.foundation.javadoc.ToDoTaglet
-taglet org.tquadrat.foundation.javadoc.UmlGraphLinkTaglet
-taglet org.tquadrat.foundation.javadoc.UnderlineTaglet

-tag note
-tag param
-tag return
-tag throws
-tag author
-tag extauthor
-tag thanks
-tag modified
-tag version
-tag since
-tag see
-tag inspired
-tag UMLGraph.link
-tag todo

This gives you the following new features:

@extauthor – A replacement for the default @author taglet that provides the author’s email as a hyperlink.
@thanks – Use this tag to add a reference to the author of the model for the current piece of code.
@modified – When code written by somebody else was modified, this tag can be used to refer to the editor.
@inspired – Sometimes a piece of code was inspired by a document of some kind, a description of an algorithm, a product white paper, or whatever. This tag allows to add a reference to that source of inspiration.
@note – With this tag, it is easy to add important notes to the documentation for an element. All notes will be added to a bullet list placed immediately beneath the documentation text (given that the tag sequence shown above is used).
@todo <task.list> – This tag can be used to add a list of open issues to the documentation for a module or a package.
@UMLGraph.link – With this tag a UML graph can be added to the documentation for a class.
{@anchor #<name> <text>} – This tag allows to add an HTML anchor to the documentation.
{@href <url> [<text>]} – With this tag a hyperlink can be added to the documentation; different from the {@link} and {@linkplain} tags, this is used to refer to external resources.
{@underline <text>} – If text needs to be underlined, this is the tag.
{@include <file> [<processMode>]} – This tag allows including other files from the source path into the JavaDoc documentation.
{@ignore <text>} – The standard tag @hidden allows to exclude the whole documentation for an element (a type, method or field) from the generated Javadoc documentation. With the tag {@ignore} it is possible to exclude just the text inside.

Details about the usage of the tags can be found in the JavaDoc.

Documentation

Javadoc Reference

Integration into Gradle

Add the following stuff to your build.gradle file:

  /**
   *  The JavaDoc taglets.
   */
  def tagletList = []
  for( def className : [
      /* The inline tags */
      "AnchorTaglet",
      "HRefTaglet",
      "IgnoreTaglet",
      "IncludeTaglet",
      "UnderlineTaglet",

      /* The block taglets - sequence is relevant! */
      "NoteTaglet",
      "AuthorTaglet",
      "ThanksTaglet",
      "ModifiedTaglet",
      "InspiredTaglet",
      "UmlGraphLinkTaglet",
      "ToDoTaglet"] )
  {
      tagletList.add( String.join( ".", "org.tquadrat.foundation.javadoc", className ) )
  }

  /**
   *  The JavaDoc tags; this defines the sequence how the tags will appear in the
   *  documentation.
   */
 def tagList = ["note", "param", "return", "throws", "author", "extauthor",
 "thanks", "modified", "version", "since", "see", "inspired",
 "UMLGraph.link", "todo" ]

configurations {
    tquadratTaglet
}   //  configurations

dependencies {
    //---* The JavaDoc extensions *--------------------------------------------
    tquadratTaglet 'org.tquadrat.tool:org.tquadrat.foundation.javadoc:0.1.0'
}   //  dependencies

tasks.named( 'javadoc' ) {
    mustRunAfter "jar"

    //---* Configure JavaDoc *-------------------------------------------------
    options {
        jFlags( "-Dorg.tquadrat.foundation.todo.base=$projectDir",
            /*
             * Refer the the additional include roots with the ${…}
             * notation.
             */
            "-Dorg.tquadrat.foundation.include.root.module=$projectDir",
            "-Dorg.tquadrat.foundation.include.root.source=$projectDir/src/main/java",
            "-Dorg.tquadrat.foundation.include.root.resources=$projectDir/src/main/resources",
            "-Dorg.tquadrat.foundation.include.root.javadoc=$projectDir/src/main/javadoc",
            "-Dorg.tquadrat.foundation.include.root.project=$projectDir/.." )

        tagletPath configurations.tquadratTaglet.files as List
        taglets tagletList
        tags tagList
    }
}