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 ) ¦