web-dev-qa-db-ja.com

ドキュメントに実際のコードを追加するJSDoc

JSDocになんらかの<code />タグがあるかどうか知っていますか？私のドキュメントに次のようなコードを追加する必要があります：

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

JSDocによってコードとして表示されるコメント内のコードが必要です（構文が強調表示されていない場合は、少なくとも事前にフォーマットされているか、背景が灰色の何かのように）。

javascriptdocumentationjsdoc
49
Marco Demaio

使用する

<pre><code>

....

</code></pre>

これは多くの公式ドキュメントで使用されているものであり、たとえば、いくつかのツールで構文の強調表示を受け取ります

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にはマークダウンプラグインがありますが、デフォルトではオフになっています。デフォルトの設定ファイルを有効にします./node_modules/jsdoc/conf.json.EXAMPLE経由...

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

...そして、コードを含むドキュメントのニース構文サポートがあります。 Markdownは3つのバックティック（```）コードブロックの境界を設定します。元の例を使用するには：

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

jsdoc の場合<code>...</code>は問題なく動作するようです。また、<pre>を追加して段落を作成する間、コードをインラインで保持します（これはとにかく行うべきことです）。 ブラウザのサポート 問題ないようですので、使用しない理由はありません。

3
SGD

JSDocには任意のHTMLを配置でき、コピーされます。私が使用するものの例を次に示します。

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

ボタンが概要にないことを確認するには、その前に文とドット（。）を追加します。

それらがロードされるように、JSDocの出力にJavaScriptファイルを含める方法を見つける必要があります。 （それ以外の場合、コードはJSDocの出力にjavascriptとして存在しません–そのためのテンプレートを変更できます： JsPlateのドキュメント を参照してください）

3
Eric

@ example の使用はほとんどの場合に機能しますが、HTMLの予約文字をリテラルに変換する必要があります：&lt;&gt;など、それ以外の場合、HTMLはレンダリングされ、コードとして表示されません。

2
LeeGee