手动 JSDoc 注释 — 创建模板答案

【问题标题】：Manual JSDoc comments — creating a template手动 JSDoc 注释 — 创建模板
【发布时间】：2017-08-12 07:51:20
【问题描述】：

我被要求为我们的开发人员创建一个 JSDoc 模板来记录他们的 ES6 代码。我不确定70 or so @ block tags 中的哪一个有用，以及我是否会因为过多的文档要求而使开发人员陷入困境。 documentation 给出了非常简单的示例，但确实没有帮助。

寻找对经验丰富的 JavaScript 开发人员最有用的块标记集的真实体验。当我问我们的问题时，他们只会说：“无论您决定什么！”，但称他们为经验丰富的 JavaScript 开发人员接近 3:1 的谎言：短语比率。

【问题讨论】：

标签： javascript ecmascript-6 jsdoc

【解决方案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
 **/

【讨论】：