JSDoc adding real code in documentation

Question

Do you know if there is a 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 argumnet that will be shown in message
*/
function foo(str)
{
   alert(str);
}

I need the code in the comments to be displaied by JSDoc as code (if not sintax highlighetd, at least like preformatted or something with grey background)

Thanks.

Answer 1

Use

<code><pre>

....

</pre></code>

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

Answer 2

@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 argumnet that will be shown in message
 */
function foo(str)
{
   alert(str);
}

Answer 3

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 "hi" with "hello".

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