标签: jsdoc3

假设我在js模块中有一个typedef类型

// somewhere/foo.js
/**
 * @module
 */ 
/**
 * @typedef Foo
 * @type {object}
 * property {string} bar - some property
 */

是否可以在另一个模块中引用此类型,以便在jsdoc生成的HTML页面中,类型显示为typedef-ed模块的链接？

我试过这种变化,但似乎没有任何作用......

// somewhere_else/bar.js
/**
 * @module
 */
/**
 * @param {somewhere/foo/Foo} foo - some param
 */
export default function doStuff(foo) {
  ...
}

只需确保在我们的 Node 服务器的模块中使用它是正确的方法，以便能够在@typedef整个应用程序中使用它，而不是在需要的每个模块/文件中重复它。从文档中我无法确定这是否正确，并且是否有人对存储全局 @typedef 的位置有意见，以便在整个应用程序中使用时是否需要更改它们很容易找到。

/**
 * Universally unique identifier.
 * @global
 * @typedef {string} UUID
 */

我正在使用documentationjs(它使用jsdoc)来处理我正在处理的lib的文档生成.我的lib编写的是ES6并且功能齐全,目前生成的文档是lib中所有模块的所有函数的字母顺序列表.这使得很难找到你想要的东西.我应该如何使用jsdoc注释,以便将一个文件中的函数组合在一起？

例如,给定以下文件...

/**
 * Docs for alpha
 */
export const alpha = () {};

/**
 * Docs for beta
 */
export const beta = ()  {};

/**
 * Docs for charlie
 */
export const charlie = () {};

...我应该如何使用jsdoc注释来确保三个函数在文档中的"示例"下组合在一起？

我已经尝试在类的顶部定义一个模块:/** @module Example */但是虽然这会在文档中生成一个名为"Example"的项目,但是函数不会在它下面进行分组.

我已经尝试添加@memberof Example各个函数的文档,但这没有任何效果.

我知道这个问题,但它对我不起作用,可能是因为ES6导入.@module在文档中没有提及它的用法.

Jsdoc是本地安装的(npm install jsdoc).尝试执行 .\node_modules.bin\jsdoc --debug ./lib/JavaScriptSource.js 输出时出现以下错误 : .\node_modules.bin\jsdoc --debug ./lib/JavaScriptSource.js 令人惊讶的是没有出现任何有用或相关的内容.

请注意,我定位的是一个 .\node_modules.bin\jsdoc --debug ./lib/JavaScriptSource.js 属性,我在Javascript中设置宽度时将其设置在一起.显然我可以让Javascript编写一个 .\node_modules.bin\jsdoc --debug ./lib/JavaScriptSource.js 类并将其作为目标,但还有其他问题需要我在CSS中完成目标.出于一个原因,设计师的工作是决定变化发生的宽度.另一个原因是,我们的目标是多个设备,而不仅仅是桌面网络浏览器.

这是目标HTML和CSS:

JSDoc 3.3.0-dev (Sun, 15 Jun 2014 18:39:52 GMT)

Options:
-t, --template <value>       The path to the template to use. Default:
                             path/to/jsdoc/templates/default
-c, --configure <value>      The path to the configuration file.
                             Default: path/to/jsdoc/conf.json 
.....
</code>

我在理解联合中命名空间和模块的目的时遇到了问题.例如,我有一个班级Game.utils.Matrix.我想Game作为命名空间,utils作为模块和Matrix类来注释:

/**
 * @namespace Game
 */

/**
 * @module utils
 * @memberOf Game
 */

/**
 * Create a matrix
 * @constructor
 */
function Matrix(){}

它创建了一个文档,并且Matrix该类的名称路径是Game.utils~ Matrix,但如果我按照Module链接,其名称路径Module: utils没有Game名称空间前缀,如果我按照Game链接它不包含utils模块链接.

此外,我无法向此模块添加另一个类,因为此类未显示在utils模块选项卡中:

/**
 * Create Dictionary
 * @memberOf Game.utils
 * @constructor
 */
function Dictionary(){}

问题是:记录命名空间和模块的正确方法是什么？每个命名空间和模块的用例是什么？

我正在开发一款将会变得非常庞大的应用程序.我决定使用JsDoc3并DocStrap记录所有模块.模块通过require.js定义,在某些地方,它们最多嵌套3或4级.

直到现在我才明白JsDoc文档分为四个主要部分:模块,类,教程,全局.每个部分都有一个标题下拉菜单和一个侧边栏,每个标题按字母顺序列出liniar方式的所有模块.

我想知道是否有选项来显示/分组模块和类以某种方式反映项目结构.我看到了一个git存储库,它记录了所有带有大量斜线的类module1/submodule1/class1,但感觉真的是要挖掘这种类型的导航.更不用说布局在侧边栏溢出的长标题方面遇到了麻烦.

目前我的项目布局类似于下面的架构.它广泛而深入,我希望它能够进一步发展.

/Editor
---/Services
------/UI
------...
---...
---editorApp.js
/Engine
---/Core
------/...
---/Entities
------/...
---/Graphics
------/...
---/...
...
engine.js
/Web
---/Services
------/UI
------...
---...
---webApp.js

我想在jsdoc 3.4.2中创建自定义标签.该config.json 文件是

{
    "tags": {
        "allowUnknownTags": true,
        "dictionaries": ["jsdoc","closure"]
    },

    "source": {
        "include": [
            "app/"
            ],
        "exclude": [],
        "includePattern": ".+\\.js(doc|x)?$",
        "excludePattern": "(^|\\/|\\\\)_"
    },
    "plugins": [
        "plugins/custom-tags.js"
        ],
    "templates": {
        "cleverLinks": false,
        "monospaceLinks": false
    },
    "opts": {
        "destination": "./docs",
        "recurse": true,
        "encoding": "utf8"
    }
}

在custom-tags.js我添加了这些行

exports.defineTags = function (dictionary) {
    dictionary.defineTag("service", {
        mustHaveValue: true,
        canHaveType: false,
        canHaveName: true,
        onTagged: function (doclet, tag) {
            doclet.service = tag.value;
        }
    });
}; 

但是当我在代码中使用@service时,它没有显示.我看了一些与此相关的链接,发现我们需要创建模板的自定义标签,但没有找到创建模板的方法.我在我的Windows机器上全局安装了jsdoc.

我有一个带有大量选项的函数：

/**
 * Show dialog in a blocking manner.
 *
 * @param {object} opts
 * @param {string} opts.msg "Body" of the dialog.
 * @param {number} opts.timeout Seconds - floating point values are rounded. (ActiveX imposes this)
 * @param {string} opts.title Title of the dialog.
 * @param {number} opts.icon Use constants for this. (See docs)
 * @param {number} opts.buttons Use constants for this. (See docs)
 * @param {number} opts.defaultButton Use constants for this. (See docs)
 * @returns {number} Use our constants …

我正在尝试 JSDoc 一个简单的带有钩子的 React Typescript 组件。不幸的是，我似乎找不到使 JSDoc 与声明的解构数组一起工作的方法。有一些 与解构对象参数相关的答案，但这些对数组不起作用。

/**
 * @property {boolean} 0 - documentation for isLoading
 * @property {func} 1 - documentation for setIsLoading
 */
 const [isLoading, setIsLoading] = React.useState<boolean>(false);

更新 1：仍然无法找到记录此解构的方法。有一个极端情况，如果我自定义键入一个对象，它会起作用：

export type AuthFormInput = {
  /** Value of the Email input field */
  email: string;
  /** Value of the Password input field */
  password: string;
};

const [form, setForm] = React.useState<AuthFormInput>({
  email: '',
  password: ''
});

...

// JSDoc will work here …

我认为JSDoc记录的所有成员/对象/等应该是他们自己的可点击链接; 例如,如果我有levelOne --> levelTwo --> levelThree --> levelFour,那么我应该在第一页上看到levelOne并且能够点击我的方式进入levelFour ...但似乎并非如此.

这是我的代码:

/**
    Contains various tools and extensions.
    @namespace App
    */
var app = app || {};


/**
Contains App plugins.
@namespace App.Plugins
*/
app.Plugins = app.Plugins || {};

/**
Contains methods and classes usable within unit-testing.
@memberof App
@type {object}
@namespace App.UnitTesting
*/
app.UnitTesting = app.UnitTesting || {
    /**
    Test methods for the App library.
    @memberof App.UnitTesting
    @type {object}
    @property {object} test1 Property definition.
    */
    PluginTests: {
        /** 
        Test …