4

フォーム入力を検証する AngularJS サービスを作成していますが、JSDoc3 を使用して合理的なドキュメントを作成する方法を一生理解できません。

理想的には、バリデータ サービスのドキュメントと、各バリデータ (内部オブジェクト) のドキュメントをエクスポートする必要があります。

少しグーグルで調べた後、名前空間を少しハッキングすることでそれを機能させることができましたが、これを行う正しい方法があるかどうか疑問に思っています。私のサービスが含まれている場合、他の誰かの JSDoc を台無しにしない方法。

例：

angular.module('services.utility')
.factory('validator', [function () {
    var validators = {
        /**
         * Requires a field to have something in it.
         * @param  {String|Boolean} val    The value to be checked.
         * @return {Object}
         */
        'required': function(val){
            // check against validator
            return {'valid': true, 'msg': 'passed!'};
        },
        /**
         * Requires a field to be less than a number.
         * @param  {Number} val    The value to be checked.
         * @param  {Number} check  The value to be checked against.
         * @return {Object}
         */
        'lessThan': function(val){
            // check against validator
            return {'valid': true, 'msg': 'passed!'};
        }
    };
    return {
        /**
         * This is the main validation routine. 
         * @param  {Object} vObjs An object to be processed.
         * @return {Boolean}
         */
        'validate': function(thingsToValidate){
            // run some validations from the validators
                    // and return a bool.
        }
    };
}]);

完璧な世界では、上記の変更により、ユーザーがバリデーター全体の使用方法について読んだり、それぞれに渡される必要があるものを調べたりできる、優れた非グローバルな JSDoc 階層を生成できます。検証の種類。

あなたが与えることができるどんな助けにも感謝します!

4

1 に答える 1

1

私のチームのやり方は、実際のファクトリ関数のみをユーザーが読むかのように文書化するというものです。あなたは実際にその男をスキップしました。いずれにせよ、それをドキュメントのエントリ ポイントとして扱い、それを「メソッド」ドキュメントと組み合わせて全体像を把握できます。これと組み合わせて @namespace ドキュメントを利用できます。

/** Here is how you use my factory. @param @return */
my.validator.factory = function() { return { validate: function(){} }; }
/** Here are some validators. @enum {Function(*):ValidationResult} **/
my.validator.Validators = {}

module.factory('validator', my.validator.factory);

本当に欲しいものによっては、プロトタイプの使用を好む場合があります。ここでドキュメントが真価を発揮します。

/** Here is how you use my factory. @param @return @constructor */
my.Validator = function() {}
/** My validation function. @param @return */
my.Validator.prototype.validate = function() {}
/** Here are some validators. @enum {Function(*):ValidationResult} **/
my.Validator.Validators = {}

module.service('validator', my.Validator);

ドキュメントでプロトタイプを使用すると、すべてがうまくまとまります。これは、バリデーターを 1 つのクラス エンティティとして文書化するようなもので、これは私にとって最も理にかなっています。

于 2013-01-22T01:56:40.660 に答える