javascript - 组织和记录多文件 JavaScript 项目

Question

我正在开始一个相当大的 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 等)

有什么想法如何将其记录下来，或者更好的安排方式吗？

谢谢。

Answer 1

昨天玩了大约四个小时的各种东西之后，我想我已经找到了最佳格式，它结合了很好的高效形式，同时允许最少的注释来正确解析内容。

"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 会失去对我的方法的跟踪，这意味着更多的注释，这并不酷。