标签: jsdoc

// My function does X and Y.
// @params {object} parameters An object containing the parameters
// @params {function} callback The callback function
function(parameters, callback) {
}

但是,我如何描述参数对象应该如何构造？例如,它应该是这样的:

{
  setting1 : 123, // (required, integer)
  setting2 : 'asdf' // (optional, string)
}

如何告诉JSDoc有关返回的对象的结构.我找到了@return {{field1: type, field2: type, ...}} description语法并试了一下:

/**
 * Returns a coordinate from a given mouse or touch event
 * @param  {TouchEvent|MouseEvent|jQuery.Event} e    
 *         A valid mouse or touch event or a jQuery event wrapping such an
 *         event. 
 * @param  {string} [type="page"]
 *         A string representing the type of location that should be
 *         returned. Can be either "page", "client" or "screen".
 * @return {{x: Number, y: Number}} 
 *         The location of the event
 */
var getEventLocation …

根据@param的JSDoc wiki,您可以指示@param是可选的

/**
    @param {String} [name]
*/
function getPerson(name) {
}

并且您可以指示内联使用的参数

function getPerson(/**String*/ name) {
}

我可以将它们组合起来,如下所示,它可以正常工作.

/**
    @param [name]
*/
function getPerson(/**String*/name) {
}

但我想知道是否有办法在可能的情况下全部内联.

在JSDoc中,如果您有一个特定类型的数组(例如字符串数组),我可以找到的最佳文档显示使用以下内容:

/**
 * @param {Array.<string>} myStrings All my awesome strings
 */
 function blah(myStrings){
     //stuff here...
 }

你如何替换下面的问号指定一个对象数组？

/**
 * @param {???????} myObjects All of my equally awesome objects
 */
 function blah(myObjects){
     //stuff here...
 }

假设您有以下内容:

var someFunc = function() {
    // do something here with arguments
}

您如何正确地记录此函数可以在JSDoc中获取任意数量的参数？这是我最好的猜测,但我不确定它是否正确.

/**
 * @param {Mixed} [...] Unlimited amount of optional parameters
 */
var someFunc = function() {
    // do something here with arguments
}

相关:php - 如何doc一个可变数量的参数

是否有一种指定的方法来声明一个方法或函数在JsDoc中返回void？目前我认为这void是默认的返回值,必须专门提供其他返回值:

/**
 * @return {Integer} The identifier for ...
 */

我有一些代码返回一个promise对象,例如使用Node库的Q库.

var Q = require('q');

/**
 * @returns ???
 */
function task(err) {
    return err? Q.reject(new Error('Some error')) : Q.resolve('Some result');
}

如何使用JSDoc记录这样的返回值？

我有一个接受一个字符串参数的函数.此参数只能包含一些已定义的可能值.记录相同内容的最佳方法是什么？应该将shapeType定义为enum或TypeDef还是其他什么？

Shape.prototype.create = function (shapeType) {
    // shapeType can be "rect", "circle" or "ellipse"...
    this.type = shapeType;
};

Shape.prototype.getType = function (shapeType) {
    // shapeType can be "rect", "circle" or "ellipse"...
    return this.type;
};

问题的第二部分shapeType是在文件中不知道可能的值,它定义shapeType为您建议的任何内容.有几个开发人员提供了多个文件,可能会添加可能的值shapeType.

PS:我正在使用 jsdoc3

编辑:这在技术上是一个2部分问题.我选择了一般性问题的最佳答案,并与处理特定问题的答案相关联.

使用jsdoc记录匿名对象和函数的最佳方法是什么？

/**
 * @class {Page} Page Class specification
 */
var Page = function() {

    /**
     * Get a page from the server
     * @param {PageRequest} pageRequest Info on the page you want to request
     * @param {function} callback Function executed when page is retrieved
     */
    this.getPage = function(pageRequest, callback) {
    }; 
};

无论是PageRequest对象还是callback存在于代码中.它们将getPage()在运行时提供.但我希望能够定义对象和功能是什么.

我可以创建PageRequest用于记录的对象:

/**
 * @namespace {PageRequest} Object specification
 * @property {String} pageId ID of the page you want.
 * …

我希望能够在JavaScript源代码中的任何地方获取这样的JSDoc注释(甚至嵌套在几层函数中,在模块中甚至是匿名函数中):

/**
 *  Used to do some important thing that needs doing that works like xyz.
 *  @param {String} whatever - some string that has some purpose
 *  @param {Function} callback - a function that needs to be run
 *  @returns {Boolean} whether or not something happened
 */
 function something(whatever, callback) {
     ...

并有一些简单的方法来产生好的降价:

##`root.something(whatever,callback)`
Used to do some important thing that needs doing that works like xyz.

*Parameters*
  `whatever {String}` some string that has some purpose
  `callback …