javascript 利用文档字符串

aurhwmvo  于 2023-03-16  发布在  Java
关注(0)|答案(3)|浏览(158)

这是一个新手问题,但我没有设法在谷歌上找到任何关于这个主题的合理简洁而又有启发性的东西。我有Sublime Text编辑器和一个很好的插件DocBlockrhttps://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没有错误,但仅生成伪头。

46scxncf

46scxncf1#

你写这封信的时候

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

如果你把你的光标放在function的正上方,当你按下回车键时,你会得到这个:

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

有很多相似的捷径。
例如,如果您将光标放在@param {[type]} foo [description]之后,按下Enter将创建一个新的*行,而写入@将向您建议(在智能意义上)所有JSDoc注解,验证将创建一个完整的行。
正确记录文件后,只需使用jsdoc CLI创建文档。
文件:http://jsdoc.app/
编辑:我刚刚意识到你的问题的答案是在您的https://github.com/spadgos/sublime-jsdocs链接,所以也许你想知道如何生成文档,所以...
安装Node.js并使用CLI命令

npm install jsdoc -g

然后,假设您希望文档的文件名为foo.js,运行以下命令:

jsdoc foo.js

这将在out目录中创建文档。
用于生成文档的所有CLI文档都在此处:http://usejsdoc.org/about-commandline.html

ui7jx7zq

ui7jx7zq2#

在全球

要让JSDoc模板生成文档,必须添加@function属性和函数名,这两个函数将出现在模板的Global部分。

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后面跟着类名。而且因为你将向类模块提供你的函数,所以你不需要声明函数为private。
但您确实解释了之前的函数是类的一部分,因此必须使用@memberOf和属性的完整路径。

  • 如果是静态成员,则以.结尾(通过return公开)。
  • 如果它是一个可示例化的方法,则以#结尾(通过此方法公开)。
  • 如果它是一个完全没有公开的私有函数,则以~结尾(以及@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的一部分,而是你模块的一部分。而且因为你将在Helper模块后面提供你的函数,所以你不需要声明函数为private。

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

模块和类

但是,因为您通过var Helper作为Class公开,通过exports作为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,代码将被放置到相应的命名空间部分。
你也要检查你的类是否不是一个混合类(只是在类的交叉处使用,但从来没有直接使用过),或者是一个接口(定义了但没有实现),如果它是其他类的@扩展。
等等。
参见文档:http://usejsdoc.org/index.html

xsuvu9jc

xsuvu9jc3#

在您的页面中:https://github.com/Tyrn/js-procr/blob/master/procr/pcn.js
您有以下行:

if (require.main !== module) return false;

这会产生以下错误:ERROR. Unable to parse xxx Line 291: Illegal return statement .
这是因为在全局范围内不允许return,所以使用以下替代:

if (require.main === module) {
    main.copyAlbum();
}

你所有的文件都会像符咒一样被制作出来。
实际上,我不知道为什么您的jsdoc命令在您的环境中不产生错误。

相关问题