Javadoc Tags

Overview

This plugin provides an export of the information written in Javadoc. Custom Tags allow to provide information to the export process to add to the generated documents. This allows you to add e.g. tags or a category to a implemented code.

The exported files can be imported into your documentation project.

Using Tags

The following tags are defined for the sdoccode plugin:

Javadoc Tag Name Placement SDoc Information Multiplicity note
sdoc.category all category 0-1 If specified at field and type level, the field takes precedence.
sdoc.subcategory all subcategory 0-1 If specified at field and type level, the field takes precedence.
sdoc.tag all tags/tag 0-unbounded Tags from field and type level are collected.
sdoc.parent all parent/parent 0-unbounded Tags from field and type level are collected.
sdoc.name field name 0-1 If not specified the name of the Java field is used as name.
sdoc.shortDescription field short-description 0-1 If not specified the first sentence at field level is used.
sdoc.notes field notes 0-1 -
sdoc.codeType field - 0-1 If not specified, defaults to 'error'.

Please refer to the appcode XSD for a description of the SDoc information.

The following information is automatically collected and cannot be overriden:

SDoc information Source
id String representation of the code.
type Always error
component The component ID of the code.
implementation/class The name of the (enumeration) class.
implementation/field The name of the (enumeration) field.
package-descripton The comment of the (enumeration) class.

Configuration

To add specific information to elements in the sdoc format, add the following Custom Tags to your maven-javadoc-plugin configuration (please refer to tags in the maven-javadoc-plugin documentation): 

<tags>
  <tag>
    <name>sdoc.category</name>
    <placement>a</placement>
    <head>Appcode-Category</head>
  </tag>
  <tag>
    <name>sdoc.subcategory</name>
    <placement>a</placement>
    <head>Appcode-Subcategory</head>
  </tag>
  <tag>
    <name>sdoc.tag</name>
    <placement>a</placement>
    <head>Appcode-Tag</head>
  </tag>
  <tag>
    <name>sdoc.parent</name>
    <placement>a</placement>
    <head>Appcode-Parent</head>
  </tag>
  <tag>
    <name>sdoc.name</name>
    <placement>f</placement>
    <head>Appcode-Name</head>
  </tag>
  <tag>
    <name>sdoc.sortKey</name>
    <placement>f</placement>
    <head>Appcode-Sort-Key</head>
  </tag>
  <tag>
    <name>sdoc.shortDescription</name>
    <placement>f</placement>
    <head>Appcode-Short-Description</head>
  </tag>
  <tag>
    <name>sdoc.notes</name>
    <placement>f</placement>
    <head>Appcode-Notes</head>
  </tag>
  <tag>
    <name>sdoc.codeType</name>
    <placement>f</placement>
    <head>Appcode-Code-Type</head>
  </tag>
</tags>

Configuration of the Javadoc-Tool may be done with the following Command-Line parameters, if you are not using the maven-javadoc-plugin or if you use a version of that pluing prior to 2.0 

<additionalparam id="apidoc">
  -tag sdoc.category:a:Appcode-Category
  -tag sdoc.subcategory:a:Appcode-Subcategory
  -tag sdoc.tag:a:Appcode-Tag
  -tag sdoc.parent:a:Appcode-Parent
  -tag sdoc.name:f:Appcode-Name
  -tag sdoc.sortKey:f:Appcode-Sort-Key
  -tag sdoc.shortDescription:f:Appcode-Short-Description
  -tag sdoc.notes:f:Appcode-Notes
  -tag sdoc.codeType:f:Appcode-Code-Type
</additionalparam>

Source Code

In Java source the comments may be placed like this: 

/**
 * The generic configuration error.
 *
 * @sdoc.name Generic
 * @sdoc.tag one
 * @sdoc.tag two
 * @sdoc.sortKey 1
 * @sdoc.shortDescription An optional <b>short</b> description.
 * @sdoc.notes Some notes on generic errors.
 * @sdoc.codeType=message
 */
GENERIC(1000),