利用docstrings

时间:2015-12-10 15:24:59

标签: javascript node.js docstring

这是一个新手问题,但我没有设法谷歌任何合理简洁但有启发性的主题。我有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没有错误,但只生成虚拟标题。

3 个答案:

答案 0 :(得分:7)

当你写这个

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»将创建一个新的*行,并写@将建议您(在intellisense中)所有JSDoc注释和验证创建了一个完整的行。

正确记录文件后,只需使用jsdoc CLI创建文档。

文档: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

答案 1 :(得分:1)

全球

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

jsdoc your-exemple.js

但是,由于你的函数是在一个匿名函数范围内(但暂时没有模块),你确实添加了@private函数来告知该函数不是真正的全局函数,而只是在其范围内可访问。但是,因为默认情况下JSDoc Generator Template会忽略privates函数,所以添加--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和完整的属性路径。

  • 如果.是静态成员(通过返回公开),则按#结束。
  • ~结束,如果它是一种可以实现的方法(通过此方式公开)。
  • 如果@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

进入Molule

但是,在您的情况下,您使用/** * 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和名称对此进行描述。因此,您之前评论的所有内容都不是Global的一部分,但现在是您的模块的一部分。因为您将在Helper模块后面提供您的功能,所以您无需将函数声明为私有。

exports

模块和类

但是,因为您通过/** * 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作为模块公开,您可以双向记录。

<script>
    var $grid = $("#list2");
    emptyMsgDiv = $("<div><span style='color:red; text-align:center;font-size:18px;display:block;'>No Workorder Found</span></div>");
    jQuery("#list2").jqGrid({
        url:'server.php',
        datatype: "json",
        mtype: 'POST',
        colNames:['WO#','Status','Customer Name','Salesman', 'Created Date', 'WO Total', 'Notes', 'Edit'],  
        colModel:[ 
               {name:'id',index:'id', align:"center"}, 
               {name:'status1',index:'status1', align:"center", width:100}, 
               {name:'status2',index:'status2', align:"center", width:50}, 
               {name:'status3',index:'status3', align:"center"}, 
               {name:'result',index:'result', align:"center", sortable:false}          
        ],
        rowNum:10,
        rowList:[10,20,30],
        pager: '#pager2',
        sortname: 'Invoice.id',
        viewrecords: true,
        height:'100%',
        autowidth:true,
        sortorder: "desc",
        height: '100%',
        loadComplete: function() {
             var ts = this;
             if (ts.p.reccount === 0) {
                 $(this).hide();
                 emptyMsgDiv.show();
             } else {
                 $(this).show();
                 emptyMsgDiv.hide();
             }
        }
    });
    emptyMsgDiv.insertAfter($grid.parent());
    </script>

命名空间或类?

Class和Namespace之间的区别就是Class通过<script> var $grid = $("#list2"); emptyMsgDiv = $("<div><span style='color:red; text-align:center;font-size:18px;display:block;'>No Workorder Found</span></div>"); jQuery("#list2").jqGrid({ url:'server.php', datatype: "json", mtype: 'POST', colNames:['WO#','Status','Customer Name','Salesman', 'Created Date', 'WO Total', 'Notes', 'Edit'], colModel:[ {name:'id',index:'id', align:"center"}, {name:'status1',index:'status1', align:"center"}, {name:'status2',index:'status2', align:"center"}, {name:'status3',index:'status3', align:"center"}, {name:'result',index:'result', align:"center", sortable:false} ], rowNum:10, rowList:[10,20,30], pager: '#pager2', sortname: 'Invoice.id', viewrecords: true, height:'100%', sortorder: "desc", height: '100%', loadComplete: function() { var ts = this; if (ts.p.reccount === 0) { $(this).hide(); emptyMsgDiv.show(); } else { $(this).show(); emptyMsgDiv.hide(); } } }); emptyMsgDiv.insertAfter($grid.parent()); </script> 公开了一些对象/函数,并且是可以实现的。如果没有附加任何内容,您可能有一个名称空间,所以只需将@class替换为@name,并将该代码放入相应的Namespace部分。

如果它是其他类的@extend,你还要检查你的Class是不是Mixin(只是在跨类使用,但从不直接使用)或接口(已定义但未实现)。

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

答案 2 :(得分:0)

在您的信息页中: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所以请使用此insteed:

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

所有文档都会像魅力一样产生。

实际上,我不知道为什么你的jsdoc命令在你的环境中没有产生任何错误。