[英]Documenting an array of objects as a parameter of callback function in JSDoc
callback.rows
is array of arbitrary length with a number of repeating fields. callback.rows
是具有多个重复字段的任意长度的数组。
How can I document each field (type, property, description) in JSDoc
? 如何在JSDoc
记录每个字段(类型,属性,描述)?
Is there possible to apply this method ? 是否可以应用此方法 ?
Or may be this solution can be accepted: 或者可以接受以下解决方案:
/**
* Get list of all documents
* @param {Function} callback Standard callback function
* @param {Error} callback.err Error object if any
* @param {Array} callback.rows Rows list
* @param {String} callback.rows[0].field1 field1
*/
var myFunc = function (callback) {
// Function body
}
Try: 尝试:
/**@param {string[]} callback.rows*/
Note that you can put any type there, not just string... Such as 请注意,您可以在其中放置任何类型,而不仅仅是字符串...
/**@param {{field1: string}[]} callback.rows */
As I mentioned the best documentation for your code is unit tests. 正如我提到的,您的代码最好的文档是单元测试。
In JSDoc
should be only main parameters documented. 在JSDoc
应该仅记录主要参数。 Ie callback
is Function
. 即callback
是Function
。 The last 3 lines should be moved into your unit test. 最后三行应移至您的单元测试中。
This art of documentation is more maintainable and provable . 这种记录技术更易于维护和证明 。
Extensive JSDoc
s are hard to read and maintain . 广泛的JSDoc
很难阅读和维护 。 Not all behavior can be documented. 并非所有行为都可以记录在案。
Not all people can correct understand this documentation. 并非所有人都能正确理解本文档。 Some people will try to change documentation on your own flavor. 有些人会尝试根据自己的喜好更改文档。
声明:本站的技术帖子网页,遵循CC BY-SA 4.0协议,如果您需要转载,请注明本站网址或者原文地址。任何问题请咨询:yoyou2525@163.com.