JSDoc adding real code in documentation
Solution 1
Use
<pre><code>
....
</code></pre>
This is whats used in many official docs, and will for instance receive syntax hightlighting with some tools
Solution 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 argument that will be shown in message
*/
function foo(str)
{
alert(str);
}
Solution 3
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
*/
Solution 4
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)
Solution 5
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.
![Marco Demaio](https://i.stack.imgur.com/8qnvs.jpg?s=256&g=1)
Marco Demaio
Just love coding all day long! Now I'm using PHP and Javascript for my daytime job. I took part in realizing all the back end application to handle the orders, contracts and invoices for a site that sells posta certificata per aziende. Language I love most is C++ Language I hate most is VB6/VB.NET Wishes: to see PHP becoming more OO with operator overloading, and Python add curly braces. I have started coding in BASIC since I was a 13 years old kid with a Commodore 64 and Apple II. During University they taught me C and C++ and JAVA and I realized even more how much I love to code. :) Funny stuff: Micro Roundcube plugin to improve the search box
Updated on July 05, 2022Comments
-
Marco Demaio almost 2 years
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).
-
Quentin about 14 yearsThat seems odd. It is invalid HTML. Pre elements may contain code elements, but not the other way around.
-
Sean Kinsey about 14 years@David, It might be that I remembered incorrectly about the order of the tags:)
-
Eric almost 14 yearsI am sorry, I just realised that is not what you wanted to do. Do you mind if I leave this comment in case it helps someone ?
-
zack over 13 yearsfrom the docs you linked : The @example tag is not intended to be used to generate "inline" examples, if you want this, you need to do it via HTML markup embedded within a @description block, using the <code> tag, for example.
-
Xantix over 10 yearsgjslint which enforces the Google JavaScript StyleGuide doesn't allow @example tags...so you might want to use the <pre><code></code></pre> solution.
-
Peter W almost 6 yearsThis is also a method supported by VS Code's Intellisense. github.com/Microsoft/vscode/issues/30062
-
user1063287 about 5 yearsI have enabled markdown plugin via
conf.json
- is there a way to display inline code, ie that which is usually achieved with single back tickslike this
? Edit: actually it does work, it's just the style of the code tags are pretty minimal by default. -
Jonathan Benn over 4 yearsVS Code (at time of writing) doesn't seem to support HTML tags though. :( I tried
<pre>
and<code>
and they were just written literally in the Intellisense. However, I just realized that Markdown seems to be supported!!! So surrounding inline code with backticks (`) works. :) -
Jonathan Benn over 4 yearsIn Visual Studio Code, Markdown support seems to be available out-of-the-box
-
ypresto about 3 yearsThis does not work for TypeScript.
@example
answer works well.