组织和记录多文件 JavaScript 项目答案

【问题标题】：Organizing and Documenting Multi-File JavaScript Projects组织和记录多文件 JavaScript 项目
【发布时间】：2013-06-14 14:58:41
【问题描述】：

我正在开始一个相当大的 JavaScript 项目。该项目将所有内容都存在于一个或多个命名空间中，因此全局范围内只会存在少量事物（目前只有一件事）。

为了使事情井井有条，我想将每个类都保存在自己的文件中（就像您对其他许多其他语言一样）而不是“模块”。

我构建了一个小编译脚本（使用 NodeJS），它将在一天结束时将所有文件编译成一个 JavaScript 文件。

我认为我有一个很好的方法，但我试图让 JSDoc(3) 与我合作并且运气不佳，所以我想知道我是否可能以错误的方式解决这个问题，或者如果我缺少 JSDoc 的一些技巧。

在源码中，每个命名空间都是一个文件夹，每个类都是一个同名文件。

每个类文件看起来像这样：

var BaseNS = BaseNS || {};
BaseNS.SubNS = BaseNS.SubNS || {};

BaseNS.SubNS.MyClass = (function() {
    function MyClass() {
    }

    Object.defineProperties(MyClass.prototype, {
       'someProp', { 
            getter: function() { return this._someProp = this._someProp || 0; },
            setter: function(val) { this._someProp = val; }
       }
       // ... more
    });

    MyClass.prototype.someMethod = function() {};
    // ... more

    return MyClass;
}}());

当一起编译时，我的编译脚本会处理依赖项以正确顺序获取类，并删除重复的命名空间声明行。

我认为这种方法比较简洁明了。问题是，我无法弄清楚如何编写 JSDoc 文档，以提供我认为应该的东西。

我想使用“类类”方法来处理事情。这实际上适用于从 DOM 中大量删除的应用程序。另外，我希望整个项目是普通的、现代的 JavaScript（即没有 RequireJS 等）

有什么想法可以记录下来，或者有更好的安排方式吗？

谢谢。

【问题讨论】：

标签： javascript documentation organization jsdoc

【解决方案1】：

昨天玩了大约四个小时后，我想我已经找到了最佳格式，它结合了很好的有效形式，同时允许最少的 cmets 正确解析。

"use strict";

/** @namespace */
var NS = NS || {};

/** @namespace */
NS.Sub = NS.Sub || {};

/**
 * @class
 */
NS.Sub.SomeClass = (function(NS) {
    /**
     * @constructor
     * @lends NS.Sub.SomeClass
     */
    var SomeClass = function() {
        /** @method */
        this.someFunc = function(cookie) {

        };

        Object.defineProperties(this, /** @lends NS.Sub.SomeClass */ {
            /**
             * @type {number}
             * @instance
             */
            somePublicProp: {
                getter: function() { return this._somePublicProp || 24; },
                setter: function(val) { this._somePublicProp = val; }
            }
        });
    };

    return SomeClass;
})(NS);

如果有人对如何使这变得更好有任何建议，我很想听听他们的意见。特别是，我想不出一种方法来摆脱对var SomeClass; ... return SomeClass 的需求。我想直接返回它（最好不带任何名称），但是 JSDoc 丢失了我的方法，这意味着更多的 cmets，这并不酷。

【讨论】：