CODEWITHSUNDEEP
javascriptdocumentationjsdoc
Marco Demaio
Marco Demaio

Reputation: 34407

JSDoc adding real code in documentation

Do you know if there is some sort of <code /> tag in JSDoc? I need to add pieces of code in my documentation like this:

/**
 * This function does something see example below:
 *
 * var x = foo("test"); //it will show "test" message
 *
 * @param {string} str: string argument that will be shown in message
 */
function foo(str)
{
   alert(str);
}

I need the code in the comments to be displayed by JSDoc as code (if not syntax highlighted, at least like pre-formatted or something with grey background).

Upvotes: 85

Views: 57526

Answers (6)

Lee Goddard
Lee Goddard

Reputation: 11173

Using @example works for most cases, but HTML reserved characters need to be translated to HTML entities: &lt; &gt; and so on, otherwise the HTML will be rendered and not displayed as code.

From the linked documentation:

/**
 * Solves equations of the form a * x = b
 * @example
 * // returns 2
 * globalNS.method1(5, 10);
 * @example
 * // returns 3
 * globalNS.method(5, 15);
 * @returns {Number} Returns the value of x for the equation.
 */
globalNS.method1 = function (a, b) {
    return b / a;
};

An example with a caption:

/**
 * Solves equations of the form a * x = b
 * @example <caption>Example usage of method1.</caption>
 * // returns 2
 * globalNS.method1(5, 10);
 * @returns {Number} Returns the value of x for the equation.
 */
globalNS.method1 = function (a, b) {
    return b / a;
};

Upvotes: 6

offlinehacker
offlinehacker

Reputation: 922

Jsdoc3 has a markdown plugin but it is turned off by default. Enable it the default config file ./node_modules/jsdoc/conf.json.EXAMPLE via ...

"plugins": [
    "plugins/markdown"
],

... and you have nice syntax support for docs, including for code. Markdown uses three backticks (```) to demarcate code blocks. For to use the original example:

/**
* This function does something see example below:
* ```
* var x = foo("test"); //it will show "test" message
* ```
* @param {string} str: string argument that will be shown in message
*/

Upvotes: 47

Eric
Eric

Reputation: 1769

You can put any HTML in JSDoc and it will be copied out. Heres an example of what I use:

/** 
 * The ReplaceSlang method replaces the string &quot;hi&quot; with &quot;hello&quot;.
 *   <script language="javascript">
 *     function testFunc() {
 *       alert(ReplaceSlang(prompt("Enter sample argument")));
 *     }
 *   </script>
 *   <input type="button" value="Test" onclick="testFunc()" />
 * @param {String} str The text to transform
 * @return {String}
 */
exports.ReplaceSlang = function(str) {
  return str.replace("hi", "hello");
};

To make sure the button is not in the summary, add a sentence and a dot (.) before it.

You need to find some way to include your javascript file in the output of JSDoc so that they are loaded. (Your code otherwise does not exist as javascript in the output of JSDoc – you can modify the template for that : see JsPlate documentation)

Upvotes: 6

SGD
SGD

Reputation: 1716

For jsdoc3 <code>...</code> seems to work just fine. It also keeps the code inline while adding in <pre> creates a paragraph (which is what it should do anyways). Browser support seems to be ok so I don't see any reason to not use it.

Upvotes: 5

Josh Johnson
Josh Johnson

Reputation: 11107

@example http://code.google.com/p/jsdoc-toolkit/wiki/TagExample

/**
 * This function does something see example below:
 * @example
 * var x = foo("test"); //it will show "test" message
 *
 * @param {string} str: string argument that will be shown in message
 */
function foo(str)
{
   alert(str);
}

Upvotes: 89

Sean Kinsey
Sean Kinsey

Reputation: 38046

Use

<pre><code>

....

</code></pre>

This is whats used in many official docs, and will for instance receive syntax hightlighting with some tools

Upvotes: 53

Related Questions