Получение jsdoc и шаблонов дизайна Crockford, чтобы ладить - PullRequest
Новая
       3

Получение jsdoc и шаблонов дизайна Crockford, чтобы ладить

9 голосов
/ 07 февраля 2011

Я использую шаблон проектирования Дугласа Крокфорда для реализации частных, привилегированных и открытых методов. В основном это выглядит примерно так (используя RequireJS ): 

define(function () {
    return function () {
        var that = {},

        _init = function () {
            // "constructor"
        },

        _privateFn = function () {
            return 42;
        };

        that.publicFn = function () {
            return 2 * _privateFn();
        };

        _init(arguments);

        return that;
    };
});

Однако у меня возникают проблемы с получением jsdoc toolkit для правильного анализа. Я играл с аннотациями @name и @memberOf (например, здесь ), но, что бы я ни делал, я просто не могу заставить функции отображаться.

Кто-нибудь знает решение?

Ответы [ 5 ]

16 голосов
/ 14 февраля 2011

Хорошо, я наконец понял это.Вот как вы это делаете: 

/**
* @name MyModule
* @namespace
*/
define(['MyModule'], (function () {
    "use strict";

    var Clazz = function (config) {
        var that = {},

        /**
        * @private
        * @type number
        * @name MyModule#_privateField
        * @field
        */
        _privateField = 42,

        /**
        * Returns a private field
        * 
        * @private
        * @memberOf MyModule#
        */
        _privateFn = function () {
            return _privateField;
        };

        /**
        * Uppercases a string value.
        * 
        * @public
        * @name MyModule#publicFn
        * @function
        * @param {string} value The value to uppercase.
        */
        that.publicFn = function (value) {
            return value.toUpperCase();
        };

        return that;
    }

    return Clazz;
}));
2 голосов
/ 10 февраля 2011

У меня было такое же забавное возиться с тэгами, чтобы попытаться заставить JsDoc Toolkit выводить что-то разумное, где что-то создавалось динамически.

Даже когда я работал, ,в итоге получились странные причуды, которые требовали от меня возиться с тэгами снова и снова, это выглядело непривлекательно и по-прежнему не заменяло надлежащую документацию - вы могли бы также прочитать эти комментарии в исходном коде.

Честно говоря, лучшее, что я когда-либо делал, - это тратил время на прыжки через обручи с помощью JsDoc Toolkit и использовал его для написания реальной документации с Sphinx .

В дополнение к неотъемлемым преимуществам любой документации, написанной людьми для людей, над автоматическими документами API, Sphinx имеет директивы домена JavaScript , которые позволяют документировать конечное состояние API , который будет доступен конечным пользователям, вместо того, чтобы пытаться понять смысл кода.API, просматривая комментарии проб и ошибок, замусоренные о вашем коде.

1 голос
/ 30 октября 2013

Не знаю, существовало ли это, когда вы пытались, но @lends значительно приятнее в использовании.

См .: http://usejsdoc.org/tags-lends.html

Пример: 

var Person = makeClass(
/** @lends Person.prototype */
{
    /** @constructs */
    initialize: function(name) {
        this.name = name;
    },
    say: function(message) {
        return this.name + " says: " + message;
    }
});
1 голос
/ 31 июля 2013

Я нашел этот вопрос, когда искал решение той же проблемы. Я закончил тем, что нашел лучший способ решить эту проблему, если вам не нужно документировать частные методы / переменные (что, вероятно, не следует делать, учитывая, что они действительно локальные переменные и к ним нельзя получить доступ откуда-либо еще). Он использует директиву @alias, которая появилась в JSDoc 3. 

/**
* @name MyModule
* @namespace
*/
define(['MyModule'], (function () {
    "use strict";

    var Clazz = function (config) {
        /** @alias MyModule.prototype */
        var that = {};

        /**
        * Uppercases a string value.
        * @param {string} value The value to uppercase.
        */
        that.publicFn = function (value) {
            return value.toUpperCase();
        };

        return that;
    }

    return Clazz;
}));
0 голосов
/ 10 февраля 2011

На самом деле я рассматриваю ООП-шаблоны Дугласа Крокфорда как анти-паттерны.Я усвоил сложный способ их не использовать.В этой статье кратко изложены их недостатки: http://bolinfest.com/javascript/inheritance.php

Таким образом, решение заключается в том, чтобы забыть об антипаттернах Крокфорда и поучиться у разработчиков, которые действительно пишут настоящий код.используйте Google Closure Compiler с его аннотациями, как вы можете видеть здесь: http://code.google.com/closure/compiler/docs/js-for-compiler.html

...