web-dev-qa-db-fra.com

JSDoc ajout de vrai code dans la documentation

Savez-vous s'il existe une sorte de <code /> tag dans JSDoc? J'ai besoin d'ajouter des morceaux de code dans ma documentation comme ceci:

/**
 * 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);
}

J'ai besoin que le code dans les commentaires soit affiché par JSDoc en tant que code (sinon la syntaxe est mise en évidence, au moins comme pré-formatée ou quelque chose avec un fond gris).

javascriptdocumentationjsdoc
49
Marco Demaio

Utilisation

<pre><code>

....

</code></pre>

C'est ce qui est utilisé dans de nombreux documents officiels et recevra, par exemple, une mise en évidence de la syntaxe avec certains outils.

36
Sean Kinsey

@examplehttp://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);
}
33
Josh Johnson

Jsdoc3 possède un plugin de démarque mais il est désactivé par défaut. Activez-le le fichier de configuration par défaut ./node_modules/jsdoc/conf.json.EXAMPLE via ...

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

... et vous avez un support de syntaxe Nice pour les documents, y compris pour le code. Markdown utilise trois backticks (```) pour délimiter les blocs de code. Pour utiliser l'exemple d'origine:

/**
* 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
*/
25
offlinehacker

Pour jsdoc<code>...</code> semble bien fonctionner. Il conserve également le code en ligne tout en ajoutant <pre> crée un paragraphe (ce qu'il doit faire de toute façon). Prise en charge du navigateur semble être ok donc je ne vois aucune raison de ne pas l'utiliser.

3
SGD

Vous pouvez mettre n'importe quel code HTML dans JSDoc et il sera copié. Voici un exemple de ce que j'utilise:

/** 
 * 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");
};

Pour vous assurer que le bouton ne figure pas dans le résumé, ajoutez-y une phrase et un point (.).

Vous devez trouver un moyen d'inclure votre fichier javascript dans la sortie de JSDoc afin qu'ils soient chargés. (Sinon, votre code n'existe pas en tant que javascript dans la sortie de JSDoc - vous pouvez modifier le modèle pour cela: voir documentation JsPlate )

3
Eric

L'utilisation de @ exemple fonctionne dans la plupart des cas, mais les caractères réservés HTML doivent être traduits en littéraux: &lt;&gt; et ainsi de suite, sinon le HTML sera rendu et non affiché en tant que code.

2
LeeGee