标签: jsdoc3

这与问题30360391类似.我想表达一个函数的参数是一个普通的JS对象,它可以具有任意属性(具有未知的)名称,但所有属性都是具有固定属性的对象本身.

一个例子:函数就是这样的

/**
 * @param {Descriptor} desc
 */
function foo( desc ) {
  // ...
}

和典型的desc外观

desc = {
  unknownEntity1: {
    priority: 5;
    writable: false;
  },
  unknownEntity2: {
    priority: 42;
    writable: true;
  },
  unknownEntity3: {
    priority: 9;
    writable: false;
  }
}

我已经有了

/**
 * @typedef {Object} DescriptorEntry
 * @property {number} priority - The priority of the entity
 * @property {boolean} writable - True, if the entity can be modified
 */

我还需要一个typedef用于Descriptor基本上表达描述符与任意属性的对象,但所有类型的 …

我是使用 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？

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

我有一个带有一个对象数组作为参数的函数,并希望使用JSDOC来描述参数(包括数组中对象的属性),如下例所示:

/**
 * @param {Array.<Object>} filter - array of filter objects
 * @param ...
 */
function doSomething(filter) {
}

过滤器是这样的:

filter = [
   {id: 'session', value: 1},
   {id: 'name', value: 'john'}
]

如何将文件的属性id,并value在jsdoc3？

/**
 * @param {String} foo
 * @param {Number} bar
 */

要么

/**
 * @param {string} foo
 * @param {number} bar
 */

JSDoc @type文档没有明确说明.

我总是大写String,Number因为我的理解是我需要使用构造函数名称.在JavaScript中,String并Number作为构造函数存在.

我注意到不一致:我定义等基本类型(例如null,undefined)为小写.

原始类型名称需要是大写还是小写？

我正在寻找记录我的代码的最佳方法,但我找不到任何东西.

我已经看到了其他主题,包括这个,但都没有解决我的问题.

我有这样的事情:

define([
    'backbone'
], function (Backbone) {

    /**
     * @module models/products
     */

    /**
     * Product model
     * @class
     */
    var Product = Backbone.Model.extend({
        /** @lends Product.prototype */

        /**
         * Some method
         * @param {String} name - Name of something
         * @return {something}
         */

         someMethod: function () {
             // ...
         }

    });

    /**
     * Products collection
     * @class
     */
    var Products = Backbone.Collection.extend({
        /** @lends Products.prototype */

        /**
         * @type {Product}
         */
        model: Product,


        /**
         * Some …

我正在尝试评论描述整体功能的整个文件。我把这样的东西放在每个文件的顶部

/**
 * @file File with helper functions that facilitate reading config JSON files.
 */

但是当我生成文档时，我最终在每个文件之前都有一个奇怪的索引标题。它看起来像这样：

我没有对默认 JSDoc 配置进行任何更改。难道我做错了什么？指数标题是什么？我可以摆脱它或将其更改为有意义的东西吗？

假设我有一些对象,使用jsdoc3评论它的方法是什么？

/**
 * Test object
 * @namespace test
 */
var test = {
    /**
     * Some defaults
     * @memberOf test
     */
    defaults: {
      'test1': 1,
      'test2': 2
    },
    /**
     * Somthing else
     * @memberOf test
     */
    deep: {
      /**
       * Some option
       * @memberOf {test.deep}
       */
      option: {},
      /**
       * Some method
       * @memberOf test.deep
       */
      method: {},
      /**
       * Some option
       * @memberOf {test.deep.evenMore}
       */
      evenMore: {
        /**
         * Some option
         * @memberOf test.deep.evenMore
         */
        test: false
      }
    } …

我正在使用JS Doc版本3(https://github.com/jsdoc3/jsdoc).当我运行该工具时,默认情况下它会生成HTML格式的文档.是否可以生成PDF格式的文档？

假设我在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) {
  ...
}

我正在使用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在文档中没有提及它的用法.