Vue.jsで書いたソースにコメントを残すための、おすすめのフォーマットを教えてください。
できればそのフォーマットに従って、実際にコメントされているソースを教えていただけると嬉しいです。
ちなみにjQueryで書かれたプロジェクトにはJSDocが使われているイメージです。
Vue.jsでJSDocが使われているプロジェクトはあまり見ない(そもそもフォーマットに従ってコメントされているのソースをあまり見ない)ため、判断できずに困っています。
Vue.jsはjavascriptの単なるライブラリであり、ソースは紛れもなくjavascriptなのだから、「javascriptを用いた場合の最適と思っているフォーマット」で良いでしょう。Vue.jsかどうかを特別視する必要はないです。
質問者が、それをJSDocだと思っているならば、JSDocで良いでしょう。
JSDocだと、ヒント表示やコード補完がエディタで出来るそうです。
少し古いですが。
JavaScriptでJSDocコメントを書くメリットとは
【Javascript】JSDocコメントの書き方、メリット
上記で出来ないとなっていたエディタ用でもエクステンションが充実しているようです。
JavaScriptのコード補完できていますか?
JavaScriptの静的解析によりコード補完やクロスリファレンスを実現するatom-ternjsの紹介
上記から抜き出すと以下のようになります。
推奨点/利点
Google JavaScript スタイルガイド - 日本語訳
全てのファイル、クラス、メソッド、プロパティにJSDocコメントが、適切なタグとデータ型を伴って記されるべきです。また名前から明白に判断できる場合を除き、プロパティ、メソッド、メソッドの引数、メソッドの戻り値を説明する文章が含まれているべきです。
補完があると何が嬉しいか
- スペルミスがなくなる
- 入力する文字を減らすことができる
- 別ファイルのメソッドや属性を確認する必要性がなくなる
サポートエディタ/開発環境
等々
エクステンション
Tern: Intelligent JavaScript Tooling
atom-ternjs
実装例
Anguler.js
React.js
コーディング例
/**
* 例示のための関数です
* @param {Number} x1 数学の点数
* @param {Number} x2 英語の点数
* @return {Number} 数学と英語の合計点
*/
function Mytest(x1, x2) {
/**
* ユーザー名を格納するための変数です
* @type {String}
*/
var userName = '';
return x1 + x2;
};
}
/**
* 〇〇の配列です
* @type {Array}
*/
var myArray = [];
/**
* 〇〇のクラス
* @constructor
*/
var myClass = function() {
/**
* 〇〇のプロパティ
* @type {Number}
*/
this.src1 = 0;
/**
* 〇〇のプロパティ
* @type {String}
*/
this.src2 = "";
}
/**
* 〇〇のクラスメソッド
* @param {Number} src1 メソッドの引数の説明
* @return {Number} メソッドの戻り値の説明
*/
myClass.prototype.myMethod(src1) {
return 0;
}
以後追記
良さそうな根拠を探してみました。
まずは少し古い記事ですが、考え方として。
JavaScriptのコメントは不要か?
そして何時ものMicrosoftとは言えますが、JavaScriptを改良してTypeScriptを作り、勢力を拡大しているように、JSDocを改良してTSDocを作っていて、普及させることができるかもしれません。
Vue CLI は、TypeScript ツールのサポートを組み込みで提供します。次期メジャーバージョンの Vue (3.x) では、クラスベースのコンポーネント API をもつ TypeScript サポートと TSX サポートの大幅な改善も予定しています。
TSDocは、TypeScriptソースファイルで使用されているdocコメントを標準化するための提案です。
JSDocが標準にならないのはなぜですか? 残念ながら、JSDocの文法は厳密には指定されていませんが、特定の実装の振る舞いから推測されます。標準のJSDocタグの大部分は、単純なJavaScriptに型注釈を提供することに夢中になっています。これは、TypeScriptなどの強く型付けされた言語にとっては無関係な懸念です。 TSDocはこれらの制限に対処しながら、より洗練された一連の目標にも取り組みます。
上記に対抗して? star を倍近く(正確には1.78倍)集めているのがこれです。
TypeStrong/typedoc
TypeScriptプロジェクト用のドキュメンテーションジェネレータ。
自動生成とあるので、楽と言えば楽ですか。JavaDocスタイルのようですが。
Document your code
TypeDocはTypeScriptコンパイラを実行し、生成されたコンパイラシンボルから型情報を抽出します。したがって、コメント内に追加のメタデータを含める必要はありません。クラス、列挙型、プロパティ型などのTypeScript固有の要素やアクセス修飾子は自動的に検出されます。
ドキュメントジェネレータは現在、次のjavadocタグを理解しています。
JSDocもツールやスタイルガイドを充実させています。
vue-styleguidist/docs/Documenting.md
vue-styleguidist/vue-styleguidist
styleguidist/react-styleguidist