10

私の Javascript 関数のほとんどは比較的単純で、その副作用のために呼び出されます。jQuery を使用して DOM を操作したり、Ajax 呼び出しを行ったりしています。私は自分の関数を「モジュール パターンを明らかにする」スタイルで書くことを好みます。

JSDoc-annotating Javascript files には利点があることを発見しました: 注釈の助けを借りて、EclipseのJS Development Tools は私の JS ファイルを解析し、Eclipse Outline View (それ以外の場合は空になります) を埋めることができます。

さて、注釈の細かい点、または良い実践は何だろうか? 私はそれに慣れていません。

Google JS スタイルガイドでは、JSDoc について次のように述べています。他のアドバイスの中でも特に、使用可能なタグのサブセットのみを使用することをお勧めします。

今のところ、このテンプレートを思いつきました(このコードは何も役に立ちません)。

/**
 * @fileOverview Say something meaningful about the js file.
 * @author <a href="mailto:my@email.net">My name</a>
 * @version 1.0.1
 */


/**
 * @namespace What the namespace contains or which apps/webpages use it
 */
if (!window['my']['namespace']) {

    window['my']['namespace'] = {};    
my.namespace = (function() {
    /**
     * Documentation string...
     * @memberOf window.my.namespace
     * @private 
     */
    var clear = function(){};


    /**
     * Documentation string...
     * @memberOf window.my.namespace
     * @public 
     */
    function delete_success(data){
        var str = "# of files affected: " + data.length; 
        $('<pre id="success"/>').html(str).appendTo('#del_0b');
        $('<pre id="success"/>').html(data.result).appendTo('#del_sf');
    }
//more code


  return {
      "method1": method1,
      "delete_success" : delete_success
      };
   })();    //my.namespace
} //end if

ここで JSDoc タグ @function または @memberOf、またはその両方を使用する必要がありますか? @field タグはどうですか？return 句も JSDoc'umented にする必要がありますか? どのタグで？@public タグは本当に使わないほうがいいのでしょうか? ここは便利だと思います。

推奨事項はありますか？小規模プロジェクト向けの優れた実用的な JSDoc スタイル ガイドを知っている人はいますか?

4

3 に答える 3

3

コードサンプルを探している場合、それらを見つけるのに最適な場所はjsdoc-usersGoogleGroupのアーカイブにあることがわかりました。私はそこでグーグルを検索するよりずっと幸運がありました、そしてあなたが質問をするならば、彼らは通常助けることについてかなり良いです。

Eclipseのサポートについて話すことはできませんが、jsdocの新しいバージョンであるjsdoc3があります。こちらのドキュメントをご覧ください。少し不完全ですが、更新が書き込まれ、レビューの準備ができていることはわかっているので、すぐに改善されるはずです。

@functionおよびに関する特定の質問については、単純な関数のドキュメントではなく、@memberofを使用することをお勧めします。@function@memberof

于 2013-03-05T02:05:16.933 に答える
0

Eclipse @memberOf(大文字の O) では、アウトライン ( Ctrl+Oショートカット) のトリックを行います。私は主にEclipseのアウトラインにJSDocを使用していますが @author、人間にも使用しています:)

@private私はプライベート関数でも使用します。

IMHO JSDTは問題ありませんが、あまり役に立ちません。最近はあまり進化していません。Eclipse JSHint プラグインを使用するか、Eclipse プラグインで TypeScript を使用する必要があります (リファクタリングを行うことはできますが、複雑さが増します)。

于 2015-08-10T08:21:44.043 に答える