如何使用 jsdoc-toolkit 记录 jQuery-ui 小部件？

Question

我如何记录这个小部件，以便工具包可以公开方法和选项。
我尝试过的所有东西都不会在闭包内看到任何东西。

/**
* @fileOverview
* @version 1.0
*/

(function($) {
    "use strict";
    $.widget('mynamespace.nameofwidget', {

        // foo should show up in the docs
        options: {
            'foo': 'bar'
        },

        // public function name and parameters should be documented
        myPublic function () {
            // code here....
        },

        // private function no need to document
        _create: function () {
            // code here....
        },

        // private function no need to document
        _setOption: function (key, value) {
            // code here....
        },
    });

})(jQuery);

[编辑]

这是我的配置文件

{
    // source files to use
    _: ['js/test/'],

    // document all functions, even uncommented ones
    a: true,

    // including those marked @private
    p: true,

    // use this directory as the output directory
    d: "js/docs/",

    // use this template
    t: "jsdoc-toolkit/templates/jsdoc",

}

这是我正在使用的命令行命令。

java -jar jsdoc-toolkit/jsrun.jar jsdoc-toolkit/app/run.js  -c=js/docs/conf/ilo.conf

[更新配置]

{
    "opts": {
        "destination": "../js/out/",
        "private": true
    },
    "tags": {
        "allowUnknownTags": true
    },
    "source": {
        "include": [ "../js/test" ],
        "includePattern": ".+\\.js(doc)?$",
        "excludePattern": "(^|\\/|\\\\)_"
    },
    "plugins": [],
    "templates": {
        "cleverLinks": false,
        "monospaceLinks": false,
        "default": {
            "outputSourceFiles": true
        }
    }
}

Answer 1

使用@name 和@namespace 指令（或者，您可以在构造函数上使用@name 指令）。以下是您的代码的示例文档：

/**                                                                                                                                                                                           
 *@fileOverview                                                                                                                                                                               
 *@version 1.0                                                                                                                                                                                
 *                                                                                                                                                                                            
 * @namespace mynamespace.nameofwidget                                                                                                                                                        
 */                                                                                                                                                                                           

(function($) {                                                                                                                                                                                
    "use strict";                                                                                                                                                                             
    $.widget('mynamespace.nameofwidget', {                                                                                                                                                    

        /**                                                                                                                                                                                   
         * @name mynamespace.nameofwidget#foo                                                                                                                                                 
         * @description Description of Foo                                                                                                                                                    
         */                                                                                                                                                                                   
        options: {                                                                                                                                                                            
            'foo': 'bar'                                                                                                                                                                      
        },                                                                                                                                                                                    

        /**                                                                                                                                                                                   
         * @name mynamespace.nameofwidget#myPublic
         * @function
         * @description some description                                                                                                                                                      
         */                                                                                                                                                                                   
        myPublic: function () {                                                                                                                                                               
            // code here....                                                                                                                                                                  
        },                                                                                                                                                                                    

        /**                                                                                                                                                                                   
         * @name mynamespace.nameofwidget#_create                                                                                                                                             
         * @function
         * @private                                                                                                                                                                           
         * @description will not show up in HTML docs, but the comments are good to have                                                                                                      
         */                                                                                                                                                                                   
        // private function no need to document                                                                                                                                               
        _create: function () {                                                                                                                                                                
            // code here....                                                                                                                                                                  
        },                                                                                                                                                                                    

        /**                                                                                                                                                                                   
         * @name mynamespace.nameofwidget#_setOption                                                                                    
         * @function
         * @private                                                                                                                                                                           
         * @param {String} key                                                                                                                                                                
         * @param {String} value                                                                                                                                                              
         * @description will not show up in HTML docs, but the comments are good to have                                                                                                      
         */                                                                                                                                                                                   
        // private function no need to document                                                                                                                                               
        _setOption: function (key, value) {                                                                                                                                                   
            // code here....                                                                                                                                                                  
        }                                                                                                                                                                                     
    });                                                                                                                                                                                       

})(jQuery);

请注意，如果在命令行中使用了-p 参数，@private 指令将不会从生成的文档中隐藏命令。

有关名称路径的更多信息，请参阅this page，有关@private 指令的更多信息，请参阅this page。