1

Vue.jsで書いたソースにコメントを残すための、おすすめのフォーマットを教えてください。
できればそのフォーマットに従って、実際にコメントされているソースを教えていただけると嬉しいです。

ちなみにjQueryで書かれたプロジェクトにはJSDocが使われているイメージです。
Vue.jsでJSDocが使われているプロジェクトはあまり見ない(そもそもフォーマットに従ってコメントされているのソースをあまり見ない)ため、判断できずに困っています。

2 件の回答 2

2

Vue.jsはjavascriptの単なるライブラリであり、ソースは紛れもなくjavascriptなのだから、「javascriptを用いた場合の最適と思っているフォーマット」で良いでしょう。Vue.jsかどうかを特別視する必要はないです。

質問者が、それをJSDocだと思っているならば、JSDocで良いでしょう。

1

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

3
  • 外部サイトへのリンクを含む回答をする場合でも、リンク先の内容の要約を回答に含めるようにしてください。リンクが切れたとしても回答の質を保つことができます。詳しくは「外部へのリンクしかない回答にはどう対応するべき?」をご参照ください。kunifさんはいつも有益なリンク先を見つけてきてくださっていて削除対象にするには惜しいので、是非一手間加えて頂けるとありがたいです。また、要約が含まれていると +1 しやすいです。どうぞよろしくお願いいたします<(_ _)>
    – nekketsuuu
    Commented 2019年1月23日 6:34
  • JSDocの使い方はわかっています。質問したいのは、JSDocがVue.jsで書いたソースに最適かどうかどうかです。 違う場合、JSDoc以外の最適なフォーマットを教えていただきたいです。 JSDocが適している場合は、実装例を教えていただきたいです。Anguler.jsとReact.jsの実装例を示してくださっていますが、Vue.jsでJSDocが使われている例を教えていただきたいです。よろしくお願いします。@kunif
    – mimi
    Commented 2019年1月23日 22:36
  • 最適を考えて着手が遅れるよりも、そこそこ評価できそうなものがあれば始めてしまうのが良いと思うのですが。まあ少し調べて追記します。
    – kunif
    Commented 2019年1月23日 23:21

この質問に回答するには、ログインする必要があります。

求めていた回答ではありませんか? のタグが付いた他の質問を参照する。