标签: jsdoc3

什么是导致JsDoc省略源链接的最简单方法？我是否必须定义自己的模板？

感谢这里找到的答案:

/sf/answers/1353545651/

我的JavaScript文档组织良好,格式正确.每个命名空间都是其中包含的方法的"父".但是,导航并不像我想的那样精细.

通过简单的命令(jsdoc file1.js file2.js)使用node.js工具编译/渲染后,文档将生成为默认模板.此默认模板在侧栏导航中显示我的命名空间,但它不显示每个包含的方法.

您可以通过向@class每个方法添加指令来伪造方法列表,但正如我们所知,它们实际上不是类.

我很想看到像这样的侧边栏导航:

My Project

 - namespace 1
    - method.a
    - method.b
    - method.c

 -namespace 2
    - method.d
    - method.e

任何我忽略的文档方向都将不胜感激.

[编辑添加:]

通过实验,@class几乎完全符合我的要求,但有一些例外:

• 它列出了名称空间之上的类.我不喜欢这样,因为名称空间是"父母".

• JavaScript在这个意义上没有类.不是那种被称为"类"的命名法.在阅读文档以查看"类"列表时,它会创建一个奇怪的断开连接.

• 它自动添加"新"运算符.并非所有方法都有构造函数......你可以看到问题!

[编辑:示例代码]

所以这是目前的结构.在我使用JSDoc注释对其进行注释之前,这是基本方法:

var app =  app || {};
app.utils = {
    whizbang: function() {},
    geegolly: function() {}
  };
app.render = {
    thestuff: function(params) {},
    thethings: function(params) {}
  }
}

因此,使用对象文字表示法,顶级是整个应用程序的"命名空间",但在其中有用于不同目的的子命名空间.在这里,我有一个特定于实用程序的子命名空间,另一个特定于渲染的子命名空间.每个都可以有属性,但更重要的是它们都包含函数.这些功能应出现在侧边栏中.现在用我目前的JSDoc模式充实它:

/** 
 * @file MyApp.js This is an awesome description of MyApp.js
 * 
 * …

我正在努力用JSDocs记录router.get调用.如果我尝试将其附加到我的路由器调用本身,我无法在页面上正确显示文档.

/**
 * Health check
 * @memberof health
 */
router.get('/happy', function(req, res) {
    res.json({ "status" : "OK" });
});

要解决它,我让函数有名字.

router.get('/happy', happy);

/**
 * Health check
 * @memberof health
 */
function happy(req, res) {
    res.json({ "status" : "OK" });
}

这有效,但我真的想找到一种方法来获得第一种方法.有没有办法记录第一个例子？我可以使用的关键字？

目标是从TypeScript代码中获取JSDoc文档.TypeDoc(TypeScript文档解决方案)的文档质量是不可接受的,因为文档针对的是JS用户,不应该充斥着特定于TypeScript实现(接口等)的细节.

目前正在转发到ES6并从JS文件生成文档在很大程度上起到了作用.除了没有赋值的属性.看来,

class A {
    /**
     * @private
     * @var _a
     */
    private _a;

    /**
     * @public
     * @var a
     */
    public a = true;
}

正在被转化为

class A {
    constructor() {
        /**
         * @public
         * @var a
         */
        this.a = true;
    }
}

虽然我会期待类似的东西

class A {
    constructor() {
        /**
         * @private
         * @var _a
         */

        /**
         * @public
         * @var a
         */
        this.a = true;
    }
}

要么

class A {
    /**
     * @private
     * @var _a
     */ …

使用JSDoc记录React高阶组件的正确方法是什么？当然,内置的React特定标签没有 - 所以什么是正确的方法？

我有一个字符串数组的数组,我无法弄清楚如何使用JSDoc记录它.

/**
@class
*/
function PostbackList() {
    /**
    @type {int}
    @default
    */
    this.TypeID = 0;
    /**
    @type {PostbackList.Field[]}
    */
    this.Fields = new Array();
    /**

    !! Issue here !!


    @type {string[][]}
    */
    this.Values = null;
}

这会导致错误.

无效的类型表达式"string [] []":预期"!","？" 或"|" 但是"["找到了.

我不知道是否应该?在类型前面指出它可以为null.

对于像这样的功能......

function example() {
  var X = 100;

  ...

  var Y = 'abc';

  ...

  return Z;
}

我需要解释一些局部变量的用途.添加这样的描述......

function example() {
  /**
   * @description - Need to explain the purpose of X here.
   */
  var X = 100;

  ...

  /**
   * @description - Need to explain the purpose of Y here.
   */
  var Y = 'abc';

  ...

  return Z;
}

...似乎没有被接受JS Doc v3.4.0.

什么是正确的语法？

PS我的一些用例需要多行注释.

JSDoc api 表示您可以像这样记录对象：

{Object.<string, number>}

并记录多种类型：

{(number|boolean)}

但是，如果我尝试指定一个可以将字符串或数字作为键的对象，则它不起作用。VSCode/JSDoc 仅将类型报告为“any”。

VSCode 不理解：

{Object.<string, number>}

我也在 中尝试过这个@typedef，或者在它自己中定义密钥@typedef没有效果。

因为我用来&获取intersection类型（就像{Object.<string, any> & {'foo': number}}我不想使用布尔值或说：

{(number|boolean)}

记录的类型最终看起来像这样：

 type Container = ({
    [x: string]: any;
  } & {
    'foo': number;
  }) | ({
    [x: number]: any;
  } & {
    'foo': number;
  })

这是不必要的冗长。

有没有办法用更简洁的输出来记录这一点？

我为node.js项目提供了大量的json模式.我可以以任何方式使用它们:

• 从".js"代码文件中将它们作为jsdoc类型访问,以提高webstorm智能感知的准确性
• 或者自动创建jsdoc类型定义

？

我是使用 JSDocs 的新手，找不到这个问题的答案。

假设我想编写这个简单的函数：

function hasQ(array, item) {return array.includes(item);}

使用 JSDoc，我会标记为：

/**
* Another way to call array.includes(item);
* @param {Array} array
* @param {*} item to test if contained in array
* @returns
*/

有没有办法让我array在第二个@param语句中标记这个词，使其引用第一个@param？

这只是一个玩具示例，但我希望它使概念清晰。