手动 JSDoc 注释——创建模板

Question

我被要求为我们的开发人员创建一个 JSDoc 模板来记录他们的 ES6 代码。我不确定 70 or so @ block tags would be useful and whether I'd be bogging down the developers with excess documentation requirements. The documentation 中的哪一个给出了非常简单的示例，这些示例确实没有帮助。

寻找对经验丰富的 JavaScript 开发人员最有用的块标记集的真实体验。当我问我们的时，他们只是说："Whatever you decide!"，但称他们为 有经验的 JavaScript 开发人员 接近 3:1 lie:phrase 的比率。

Answer 1

我发现以下内容提供了足够的信息，不会给开发人员带来负担。

对于类：

/**
 * The XYZ class description .... In this class function1, and
 * function2 are intended for external use.
 *
 * @author        ...
 * @version       1.0
 * @see           XYZ.function1
 * @see           XYZ.function2
 **/

对于构造函数：

/**
 * The constructor ...
 *
 * @author        ...
 * @constructor
 * @this          instance of XYZ
 **/

对于构造函数中的私有成员：

/** @private **/ this.x = 1;
/** @private **/ this.y = 2;
/** @private **/ this.z = 3;

对于函数：

/**
 * The function ...
 *
 * @author        ...
 * @param         {type|otherType} X - description
 * @param         {type=} Y - optional, description
 * @param         {type=3} Z - default value, description
 * @return        {type} - description, omit if nothing returned
 * @this          instance of XYZ, or XYZ class for static functions
 * @private       omit if not private
 * @see           XYZ.function, provide if another function is relevant
 * @throws        exception, omit if no exceptions are thrown
 **/

手动 JSDoc 注释——创建模板

Manual JSDoc comments — creating a template

javascript

jsdoc

ecmascript-6