【JavaScript】 windowsでJSDocを使用する

更新日:2020/05/14

JSDocってコメントの書き方の一つだと思っていたのですが、コメントを元にhtmlで仕様書を作成できるんですね。

そこで僕のパソコン上に必要なものをインストールして、実際に仕様書を生成してみました。

ちなみに僕のパソコンはWindows10です。

 

Node.jsのインストール

JSDocの最新バージョンは 3.6.4で、Node.js上で動くようです。

そのためWindowsにNode.jsをインストールする必要があります。
幸いにも、以前インストールしてあったのでサクッと次にいくことができました。

まだインストールできてない人は、こちらを見てください。
参考:Windows10にNode.jsインストール・ブラウザ表示までの要点メモ

 

JSDocのインストール

Node.jsのインストールが終わったら、コマンドプロンプト開いて、次のコマンドを実行します。

c:\Users\kchan > npm install -g jsdoc
C:\Users\kchan\AppData\Roaming\npm\jsdoc -> C:\Users\kchan\AppData\Roaming\npm\node_modules\jsdoc\jsdoc.js
+ jsdoc@3.6.4
added 24 packages from 21 contributors in 2.943s

-gを使用すると、npmの共通フォルダにインストールされます。
そのため、どこで実行しても大丈夫です。

 

JSDocのテスト

今回はテスト用に、適当なJSDocを記述したJavaScriptファイルを二つ用意しました。

test1.js

/**
 * 文字列を加工する関数
 * @param {string} a
 * @param {number} b
 * @return {string} - f2()からリターン
 */
function f(a,b) {

    return f2( { a: a , b : b } );
}

test2.js

/**
 * オブジェクトから人物情報を生成する関数
 * @param {object} obj 受け取ったオブジェクト
 * @param {string} obj.a テキスト
 * @param {string} obj.b 数値
 * @return {object} res 生成した人物情報
 * @return {string} res.name 名前
 * @return {number} res.age 年齢
 */
function f2(obj) {

    return {name:obj.a , age: obj.b};

}

jsdocを実行する前に、新規でフォルダを作成します。

c:\Users\kchan > mkdir test

jsdocを実行すると、現在のフォルダにoutという名前のフォルダを作成され、その中にhtmlなどのデータが生成されます。

作成したフォルダに移動して、jsdoc.cmdを実行します。

c:\Users\kchan > cd test
c:\Users\kchan > jsdoc.cmd C:\Users\kchan\js\フォルダ名

今回はフォルダを指定しましたが、ファイル名でも大丈夫です。

生成されたoutフォルダに移動して、index.htmlをブラウザ表示します。

c:\Users\kchan > cd out
c:\Users\kchan > index.html

地味ですが、TOPページが表示されます。

jsdoc 生成したTOPページ

地味ですが、関数の情報が表示されます。

jsdoc 生成した関数情報

地味ですが、ソースが表示されます。

jsdoc 生成したソースページ

更新日:2020/05/14

書いた人(管理人):けーちゃん

スポンサーリンク

記事の内容について

null

こんにちはけーちゃんです。
説明するのって難しいですね。

「なんか言ってることおかしくない?」
たぶん、こんなご意見あると思います。

裏付けを取りながら記事を作成していますが、僕の勘違いだったり、そもそも情報源の内容が間違えていたりで、正確でないことが多いと思います。
そんなときは、ご意見もらえたら嬉しいです。

掲載コードについては事前に動作確認をしていますが、貼り付け後に体裁を整えるなどをした結果動作しないものになっていることがあります。
生暖かい視線でスルーするか、ご指摘ください。

ご意見、ご指摘はこちら。
https://note.affi-sapo-sv.com/info.php

 

このサイトは、リンクフリーです。大歓迎です。