组织和记录多文件JavaScript项目

Organizing and Documenting Multi-File JavaScript Projects

本文关键字：文件 JavaScript 项目 记录      更新时间：2023-09-26

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

有什么办法让这个文档化，或者更好的方式来安排事情吗?

谢谢。

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

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

相关文章：