1

大規模なコードベースを文書化する方法を理解するのに苦労しています。一連のコンポーネントがあり、そのほとんどにバックボーン モデル、ビュー、およびコレクションがあります。YUIdocs が標準ツールとして選ばれました。ドキュメントが実際に役立つことを確認したいのですが、業界ですでに決定されている可能性のあるいくつかの標準については確信が持てません.

以下を文書化するにはどうすればよいですか？

  • シンプルなバックボーン モデル:

    define(['backbone'], function (Backbone) {
    return Backbone.Model.extend({
        defaults: {
            foo: '',
            bar: '',
            baz: ''
        }
    });
});

  • モジュールのデフォルトにマージされる設定オブジェクトを受け入れるコンストラクター。YUIdocs に @default パラメータがあるようですが、オブジェクトをサポートしていないようです。

    initialize: function (settings) {
    this.settings = _.extend(this.settings, settings);
}

  • イベントやモデルなどの標準バックボーン パラメータ。

    events: {
    'click #foo' : 'bar'
}

model: foo
4

1 に答える 1

4

単純なバックボーン モデルの場合、返されるオブジェクトを文書化します。YUIDoc では、「クラス」と呼ばれます。インスタンス化も可能で ("new" キーワードを使用します)、他のオブジェクトを拡張します。したがって、次のように開始します。

/**
 * A customized Backbone.Model that represents...
 * @class MyModel
 * @constructor
 * @extends Backbone.Model
 */
return Backbone.Model.extend({

デフォルトの属性 foo、bar、および baz は、@attribute で文書化できます。属性は、実際には YUI のかなり専門的な概念ですが、少し戻ってみると、バックボーン モデルの属性は概念的に似ています。ですから、用語を借りるのは理にかなっていると思います。それ以外の場合は、@property を使用できます。

/**
 * Indicates that...
 *
 * @attribute rendered
 * @default ''
 * @type String
 */
 foo: ''

設定オブジェクトを受け入れるコンストラクターで、その設定オブジェクトに特定のデフォルト値がある場合は、Y.Router のドキュメントのソースを参照してください: http://yuilibrary.com/yui/docs/api/files/app_js_router.js.html #l38

イベントやモデルなどの標準のバックボーン パラメータには、@property を使用します。イベントの場合、どのイベント リスナーを設定するかを平易な英語で説明する必要があります。

幸運を祈ります。IRC を使用している場合、YUIDoc に関する質問がある場合は、freenode.net の #yui でチャイムを鳴らしてください。

于 2013-03-03T16:05:02.027 に答える