質問: Vue.jsで書いたソースにコメントを残すための、おすすめのフォーマットを教えてください。 できればそのフォーマットに従って、実際にコメントされているソースを教えていただけると嬉しいです。 ちなみにjQueryで書かれたプロジェクトにはJSDocが使われているイメージです。 Vue.jsでJSDocが使われているプロジェクトはあまり見ない(そもそもフォーマットに従ってコメントされているのソースをあまり見ない)ため、判断できずに困っています。
回答: JSDocだと、ヒント表示やコード補完がエディタで出来るそうです。 少し古いですが。 JavaScriptでJSDocコメントを書くメリットとは 【Javascript】JSDocコメントの書き方、メリット 上記で出来ないとなっていたエディタ用でもエクステンションが充実しているようです。 JavaScriptのコード補完できていますか? JavaScriptの静的解析によりコード補完やクロスリファレンスを実現するatom-ternjsの紹介 上記から抜き出すと以下のようになります。 **推奨点/利点** * Googleのスタイルガイドでも推奨 * エディタレベルでコードヒント/コード補完がサポート済み * ライブラリのソースコード上で関数の仕様確認が出来る * APIリファレンス/クロスリファレンス作成が容易 Google JavaScript スタイルガイド - 日本語訳 > > 全てのファイル、クラス、メソッド、プロパティにJSDocコメントが、適切なタグとデータ型を伴って記されるべきです。また名前から明白に判断できる場合を除き、プロパティ、メソッド、メソッドの引数、メソッドの戻り値を説明する文章が含まれているべきです。 > > > 補完があると何が嬉しいか > > * スペルミスがなくなる > * 入力する文字を減らすことができる > * 別ファイルのメソッドや属性を確認する必要性がなくなる > > > サポートエディタ/開発環境 * WebStorm * Visual Studio * Brackets * Sublime Text * Atom * EMacs * Vim * Light Table * Eclipse * TextMate 等々 エクステンション Tern: Intelligent JavaScript Tooling atom-ternjs 実装例 Anguler.js React.js * 先頭行は「/**」 + 「改行」 でスタート * 途中は「半角スペース」 + 「*」 + 「半角スペース」+ 「説明文」 * 最終行は「半角スペース」 + 「*/」 * 型情報等を@typeや@paramというキーワードとともに記述 コーディング例 ``` /** * 例示のための関数です * @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を作っていて、普及させることができるかもしれません。 TypeScript のサポート - Vue.js > > Vue CLI は、TypeScript ツールのサポートを組み込みで提供します。次期メジャーバージョンの Vue (3.x) では、クラスベースのコンポーネント API をもつ TypeScript サポートと TSX サポートの大幅な改善も予定しています。 > > > Microsoft/tsdoc > > 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