让 jsdoc 和 Crockford 的设计模式相处融洽

Question

我正在使用 Douglas Crockford 的 design pattern 来实现私有、特权和公共方法。它基本上看起来像这样（使用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 注释（如here），但无论我做什么，我都无法显示这些功能。

有人知道解决办法吗？

Answer 1

好吧，我终于想通了。以下是你的做法：

/**
* @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;
}));

Answer 2

我玩弄标签以尝试让 JsDoc Toolkit 在动态构建的地方输出一些合理的东西也有类似的乐趣。

即使是I got it working，它最终还是出现了奇怪的怪癖，需要我一次又一次地摆弄标签，它看起来没有吸引力，仍然不能替代适当的文档——你不妨阅读那些 cmets源代码。

老实说，我做过的最好的事情就是花时间在 JsDoc Toolkit 上跳跃，然后将它用于 write some real documentation 和 Sphinx。

除了人们为人们编写的任何指导性文档而不是自动生成的 API 文档的固有好处之外，Sphinx 还具有 JavaScript domain directives，它允许您记录将向最终用户公开的 final state of the API，而不是拥有一些代码试图通过查看散布在您的代码中的反复试验的 cmets 来理解 API。

Answer 3

我在寻找相同问题的解决方案时发现了这个问题。如果您不关心记录私有方法/变量（您可能不应该这样做，因为它们实际上是局部变量并且无法从其他任何地方访问），我最终找到了一种更好的方法来解决这个问题。它使用 @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;
}));

Answer 4

不知道您尝试时是否存在，但@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;
    }
});

Answer 5

实际上，我认为 Douglas Crockford 的 OOP 模式是反模式。我学会了不使用它们的艰难方法。本文总结了它们的缺点：http://bolinfest.com/javascript/inheritance.php

因此，解决方案就是忘记 Crockford 的反模式，向真正编写真实代码的开发人员学习。

如果您坚持使用私有，我建议您使用带有注释的 Google Closure Compiler，如您在此处看到的：http://code.google.com/closure/compiler/docs/js-for-compiler.html