利用docstrings

Question

这是一个新手问题,但我没有设法谷歌任何合理简洁但有启发性的主题.我有Sublime Text编辑器和一个优秀的插件DocBlockr https://github.com/spadgos/sublime-jsdocs,这使得正确的评论变得轻而易举.在完成评论后我该怎么做？至少,我希望能够在REPL中调用注释.还有哪些文档明智？对于中等脚本,我想要轻量级和简单的东西.

编辑:

var helper = exports.helper = (function() {

...

  /**
   * Reduces a sequence of names to initials.
   * @param  {String} name  Space Delimited sequence of names.
   * @param  {String} sep   A period separating the initials.
   * @param  {String} trail A period ending the initials.
   * @param  {String} hyph  A hypen separating double names.
   * @return {String}       Properly formatted initials.
   */
  function makeInits(name, sep, trail, hyph) {
    function splitBySpace(nm) {
      return nm.trim().split(/\s+/).map(function(x) {return x[0]}).join(sep).toUpperCase();
    }
    return name.split(hyph).map(splitBySpace).join(hyph) + trail;
  }
  /**
   * Reduces a sequence of names to initials.
   * @param  {String} name Space delimited sequence of names.
   * @return {String}      Properly formatted initials.
   */
  function makeInitials(name) {
    return makeInits(name, '.', '.', '-');
  }

...

})();

与$ jsdoc src.js没有错误,但只有假头产生.

Answer 1

当你写这个

function bar (foo) {
    return foo + foo;
}

如果您将光标放在上面的行中,function并/**在按«Enter»时写入,您将获得以下信息:

/**
 * [bar description]
 * @param  {[type]} foo [description]
 * @return {[type]}     [description]
 */
function bar (foo) {
    return foo + foo;
}

有很多类似的短缺.

例如,如果您将光标放在后面@param {[type]} foo [description],按«Enter»将创建一个新的*行,而write @将建议您(在intellisense中)所有JSDoc注释,并验证创建一个完整的行.

正确记录文件后,只需使用jsdocCLI创建文档即可.

文档:http://usejsdoc.org/

编辑:我刚刚意识到你的问题的答案在你的https://github.com/spadgos/sublime-jsdocs链接中,所以也许你想知道如何生成文档所以......

安装Node.js并使用CLI命令

npm install jsdoc -g

然后,假设您想要文件的文件名foo.js,运行以下命令:

jsdoc foo.js

这将在out目录中创建文档.

生成doc的所有CLI文档都在这里:http://usejsdoc.org/about-commandline.html

Answer 2

在全球

要允许 JSDoc 模板生成您的文档，您必须添加@function具有函数名称的属性。您的两个函数将出现在模板的全局部分。

jsdoc your-exemple.js

但是，由于您的函数在匿名函数中（但暂时没有模块），您确实添加了 @private 函数以通知该函数不是真正的全局函数，而只是在其范围内可访问。但是，因为默认情况下 JSDoc 生成器模板会忽略私有函数，所以添加--private选项。

jsdoc your-exemple.js --private

所以你的代码看起来像这样。

(function () {
    "use strict";

    // ...

    /**
     * Reduces a sequence of names to initials.
     * @function makeInits
     * @private
     * @param  {String} name  Space Delimited sequence of names.
     * @param  {String} sep   A period separating the initials.
     * @param  {String} trail A period ending the initials.
     * @param  {String} hyph  A hypen separating double names.
     * @return {String}       Properly formatted initials.
     */
    function makeInits(name, sep, trail, hyph) {
        function splitBySpace(nm) {
            return nm.trim().split(/\s+/).map(function (x) { return x[0]; }).join(sep).toUpperCase();
        }
        return name.split(hyph).map(splitBySpace).join(hyph) + trail;
    }

    /**
     * Reduces a sequence of names to initials.
     * @function makeInitials
     * @private
     * @param  {String} name Space delimited sequence of names.
     * @return {String}      Properly formatted initials.
     */
    function makeInitials(name) {
        return makeInits(name, '.', '.', '-');
    }

    // ...

}());

走进课堂

如果您将匿名闭包的内容暴露给一个变量var Helper，它可能是一个类。因此，您的代码将不是全局内容的一部分，而是@class跟随类名的类的一部分。并且因为您将向类模块提供您的函数，所以您无需将函数声明为私有。

但是你确实解释了你以前的函数是类的一部分，所以你必须使用@memberOf完整的属性路径。

• 通过结束.，如果它是一个静态成员（通过回暴露）。
• 通过结束#，如果它是一个方法instanciable（通过此暴露）。
• 通过结束~，如果它是在所有的（而不是暴露私有函数@private）。

所以

/**
 * Helper Class
 * @Class Helper
 */
var Helper = (function () {
    "use strict";

    // ...

    /**
     * Split by Space
     * @function privateExemple
     * @private
     * @memberOf Helper~
     * @return {String}     ...
     */
    function privateExemple() {
        return "";
    }

    /**
     * Reduces a sequence of names to initials.
     * @function makeInits
     * @memberOf Helper.
     * @param  {String} name  Space Delimited sequence of names.
     * @param  {String} sep   A period separating the initials.
     * @param  {String} trail A period ending the initials.
     * @param  {String} hyph  A hypen separating double names.
     * @return {String}       Properly formatted initials.
     */
    function makeInits(name, sep, trail, hyph) {
        function splitBySpace(nm, sep) {
            return nm.trim().split(/\s+/).map(function (x) { return x[0]; }).join(sep).toUpperCase();
        }
        return name.split(hyph).map(splitBySpace).join(hyph) + trail;
    }

    /**
     * Reduces a sequence of names to initials.
     * @method makeInitials
     * @memberOf Helper#
     * @param  {String} name Space delimited sequence of names.
     * @return {String}      Properly formatted initials.
     */
    this.makeInitials = function makeInitials(name) {
        return makeInits(name, '.', '.', '-');
    }

    // ...

    return {
        makeInits: makeInits
    };
}());

走进摩尔

但是，在您的情况下，您使用的exports是，这意味着您的文件是一个模块。所以你必须用@module名字来描述它。因此，您之前评论的所有内容都不是 Global 的一部分，而是您的 Module 的一部分。因为您将在 Helper 模块后面提供您的函数，所以您无需将函数声明为私有。

/**
 * Helper Module
 * @module Helper
 */
exports.helper = (function () {
    "use strict";

    // ...

    /**
     * Reduces a sequence of names to initials.
     * @function makeInits
     * @memberOf module:helper.
     * @param  {String} name  Space Delimited sequence of names.
     * @param  {String} sep   A period separating the initials.
     * @param  {String} trail A period ending the initials.
     * @param  {String} hyph  A hypen separating double names.
     * @return {String}       Properly formatted initials.
     */
    function makeInits(name, sep, trail, hyph) {
        function splitBySpace(nm) {
            return nm.trim().split(/\s+/).map(function (x) { return x[0]; }).join(sep).toUpperCase();
        }
        return name.split(hyph).map(splitBySpace).join(hyph) + trail;
    }

    /**
     * Reduces a sequence of names to initials.
     * @function makeInitials
     * @private
     * @memberOf module:helper~
     * @param  {String} name Space delimited sequence of names.
     * @return {String}      Properly formatted initials.
     */
    function makeInitials(name) {
        return makeInits(name, '.', '.', '-');
    }

    // ...

    return {
        makeInitials: makeInitials
    };
}());

模块和类

但是，因为您将 viavar Helper作为 Class 和 viaexports作为 Module公开，所以您可以以两种方式进行记录。

/**
 * Helper Class
 * @class Helper
 * @memberOf module:helper~
 * @see  {@link module:helper|Module}
 */
var Helper = (function () {
    "use strict";

    // ...

    /**
     * Reduces a sequence of names to initials.
     * @function makeInits
     * @memberOf module:helper.
     * @param  {String} name  Space Delimited sequence of names.
     * @param  {String} sep   A period separating the initials.
     * @param  {String} trail A period ending the initials.
     * @param  {String} hyph  A hypen separating double names.
     * @return {String}       Properly formatted initials.
     */
    function makeInits(name, sep, trail, hyph) {
        function splitBySpace(nm) {
            return nm.trim().split(/\s+/).map(function (x) { return x[0]; }).join(sep).toUpperCase();
        }
        return name.split(hyph).map(splitBySpace).join(hyph) + trail;
    }

    /**
     * Reduces a sequence of names to initials.
     * @function makeInitials
     * @private
     * @memberOf module:helper~
     * @param  {String} name Space delimited sequence of names.
     * @return {String}      Properly formatted initials.
     */
    function makeInitials(name) {
        return makeInits(name, '.', '.', '-');
    }

    // ...

    return {
        makeInitials: makeInitials
    };
}());

/**
 * helper Module
 * @module helper
 */
exports.helper = Helper;

命名空间还是类？

类和命名空间之间的区别只是类通过公开一些对象/函数this并且是不可实例化的。如果没有附加任何内容，则您可能有一个命名空间，因此只需将 @class 替换为 @namespace，该代码将放入适当的命名空间部分。

您还可以检查您的 Class 是否不是 Mixin（只是在 Class 上使用，但从不直接使用）或接口（已定义但未实现），如果它是其他类的 @extend。

等等。

请参阅文档：http : //usejsdoc.org/index.html