Skip to content

JavaDoc

Java, Java/Type/CoffeeScript and PHP all support java/jsdoc (/** ... */), which makes use of @tags. The tag structure is preserved when rewrapping.

language: "javascript"

/**                        ¦         ->      /**                        ¦
 * Description of the function.               * Description of the      ¦
 * @param {string} str     ¦                  * function.               ¦
 * @returns {string}       ¦                  * @param {string} str     ¦
 * The return value        ¦                  * @returns {string} The   ¦
 */                        ¦                  * return value            ¦
function convert(str) {                       */
                                             function convert(str) {

language: "coffeescript"

Coffeescript has two common comment styles, and in each case the positioning of the #/* characters is preserved.

###*                       ¦         ->      ###*                       ¦
 * Description of the function.               * Description of the      ¦
 * @param {string} str     ¦                  * function.               ¦
 * @returns {string}       ¦                  * @param {string} str     ¦
 * The return value        ¦                  * @returns {string} The   ¦
 ###                       ¦                  * return value            ¦
                                              ###

###*                      ¦         ->      ###*                      ¦
# Description of the function.              # Description of the      ¦
# @param {string} str     ¦                 # function.               ¦
# @returns {string}       ¦                 # @param {string} str     ¦
# The return value        ¦                 # @returns {string} The   ¦
###                       ¦                 # return value            ¦
                                            ###

Tags

language: "javascript"

Where a line starts with a tag, it starts a new paragraph for wrapping.

/**            ¦       ->      /**            ¦
 * Text        ¦                * Text        ¦
 * @tag text text               * @tag text   ¦
 */            ¦                * text        ¦
                                */

This holds for every tag in a run of consecutive tags.

/**            ¦       ->      /**            ¦
 * @a one      ¦                * @a one      ¦
 * @b two      ¦                * @b two      ¦
 * @c three    ¦                * @c three    ¦
 * @d four     ¦                * @d four     ¦
 */            ¦                */            ¦

Where a tag stands alone on a line, the line break after it is preserved and text on the following line is not wrapped with it. Sometimes this style is preferred:

/**                    ¦          ->      /**                    ¦
 * @description        ¦                   * @description        ¦
 * Long description that                   * Long description    ¦
 * starts on the next line.                * that starts on the  ¦
 */                    ¦                   * next line.          ¦
                       ¦                   */                    ¦

Also, the @example tag is a special case: all lines between it and the following tag are assumed to be code and therefore ignored for wrapping.

/**                          ¦      ->      /**                          ¦
 * @example                  ¦               * @example                  ¦
 * // returns 2              ¦               * // returns 2              ¦
 * Math.abs(3 - 5)           ¦               * Math.abs(3 - 5)           ¦
 *                           ¦               *                           ¦
 * // returns 5              ¦               * // returns 5              ¦
 * Math.abs(1 - 6)           ¦               * Math.abs(1 - 6)           ¦
 * @returns {Number}         ¦               * @returns {Number} Absolute¦
 * Absolute value of         ¦               * value of the number given.¦
 * the number given.         ¦               */                          ¦
 */                          ¦                                           ¦

An @example tag with text on the same line however, is treated as any other (used in php docs)

language: "php"

/**             ¦          ->      /**             ¦
 * text         ¦                   * text         ¦
 * @example url text1               * @example url ¦
 * text2        ¦                   * text1 text2  ¦
 */             ¦                   */             ¦

Inline tags

Inline tags are not broken up

/**            ¦           ->      /**            ¦
 * {@link a b \} c} d               * {@link a b \} c}
 * e           ¦                    * d e         ¦
 */            ¦                    */            ¦

Nor are they changed in lines that aren't wrapped, such as in a table or HTML block (#13, #47).

language: "java"

/**                 ¦      ->      /**                 ¦
 * | x | y |        ¦               * | x | y |        ¦
 * | -- | -- |      ¦               * | -- | -- |      ¦
 * | {@link a} | |  ¦               * | {@link a} | |  ¦
 * a                ¦               * a b              ¦
 * b                ¦               */                 ¦
 */                 ¦

/**                 ¦      ->      /**                 ¦
 * a                ¦               * a b              ¦
 * b                ¦               *                  ¦
 *                  ¦               * <p>{@link a b}   ¦
 * <p>{@link a b}   ¦               */                 ¦
 */                 ¦

language: "c++"

/**                 ¦      ->      /**                 ¦
 * a                ¦               * a b              ¦
 * b                ¦               *                  ¦
 *                  ¦               * <p>{@link a b}   ¦
 * <p>{@link a b}   ¦               */                 ¦
 */                 ¦

language: "javascript"

/**                 ¦      ->      /**                 ¦
 * a                ¦               * a b              ¦
 * b                ¦               *                  ¦
 *                  ¦               * <p>{@link a b}   ¦
 * <p>{@link a b}   ¦               */                 ¦
 */                 ¦

Or when they end up in a line's prefix, such as in a footnote label

/**                           ¦      ->      /**                           ¦
 * [^{@link a}]: text         ¦               * [^{@link a}]: text more    ¦
 * more                       ¦               */                           ¦
 */                           ¦

language: "php"

Technical details

A * at the beginning of each line is conventional but not required. The prefix or each line is preserved.

Conventional:

/**    ¦      ->   /**    ¦
 * a   ¦            * a b ¦
 * b c ¦            * c   ¦
 */    ¦            */    ¦

Star absent on first line:

/**        ¦        ->      /**        ¦
   aaa bbb ccc                 aaa bbb ¦
 * ddd     ¦                 * ccc ddd ¦
 */        ¦                 */        ¦

Irregular placement:

/**        ¦        ->      /**        ¦
*  aaa bbb ccc              *  aaa bbb ¦
 * ddd     ¦                 * ccc ddd ¦
*/         ¦                */         ¦

Stars in content

/**            ¦      ->      /**            ¦
 * List:       ¦               * List:       ¦
 * * Item A    ¦               * * Item A    ¦
 * * Item B    ¦               * * Item B    ¦
 */            ¦               */            ¦

Since the *'s are optional, they should not be consumed if used as bullets in a comment where leading *'s are absent.

/**         ¦      ->      /**         ¦
List:       ¦              List:       ¦
 * Item A   ¦               * Item A   ¦
 * Item B   ¦               * Item B   ¦
*/          ¦              */          ¦

Since the *'s are optional, they should not be consumed if used as bullets in a comment where leading *'s are absent.

Unfortunately the following case fails. The bullets are incorrectly interpreted as leading *'s.

/** List:
* Item A
* Item B
*/

Relevant: https://www.doxygen.nl/manual/markdown.html#mddox_stars

First line of the comment

language: "javascript"

Tags and inline tags are handled in the same way on the first line of the comment as on any other.

/** aaa {@link a b} */      ->      /** aaa           ¦
                  ¦                  * {@link a b} */ ¦

/// aaa {@link a b}         ->      /// aaa           ¦
                  ¦                 /// {@link a b}   ¦

/** @example       ¦      ->      /** @example       ¦
 * f( a )          ¦               * f( a )          ¦
 * g( b )          ¦               * g( b )          ¦
 */                ¦               */                ¦

/// @example       ¦      ->      /// @example       ¦
/// f( a )         ¦              /// f( a )         ¦
/// g( b )         ¦              /// g( b )         ¦