如何使用 JSDoc 记录 ES6 类属性

Posted 2023-02-18

【中文标题】如何使用 JSDoc 记录 ES6 类属性

【英文标题】：How to use JSDoc to document an ES6 class property

【发布时间】：2018-12-30 06:12:46

【问题描述】：

我正在使用documentation package，但不知道如何将其用于文档类属性（不是通过 getter 和 setter 定义的）。

因为下面只是为 SomeClass 生成类文档，但省略了 someProperty 文档。

/**
 * SomeClass is an example class for my question.
 * @class
 * @constructor
 * @public
 */
class SomeClass 
    constructor () 
        this.someProperty = true  // how do I document this?
    

    /**
     * someProperty is an example property that is set to `true`
     * @property boolean someProperty
     * @public
     */

顺便说一句：jsdoc 类上的@constructor 是documentation thing。

【问题讨论】：

@instance 工作吗？

看起来不像，或者至少从我的尝试来看。

你不需要@class，因为 JSDoc 已经知道它是一个类。

【参考方案1】：

将 someProperty 的 JSDoc 移动到第一次定义它的构造函数中：

/**
 * SomeClass is an example class for my question.
 * @class
 * @constructor
 * @public
 */
class SomeClass 
    constructor () 
        /**
         * someProperty is an example property that is set to `true`
         * @type boolean
         * @public
         */
        this.someProperty = true
    

我不确定是否有办法通过documentation package 使用不涉及将 JSDocs 内联到构造函数中的方法来完成它。

【参考方案2】：

另一种方法是在类文档中声明它们如下：

/**
 * Class definition
 * @property type propName - propriety description
 * ...
 */
class ClassName 
  constructor () ...
  ...

【讨论】：

这对我来说不适用于 VSCode 智能感知，但 balupton 的解决方案可以。

Visual Studio 2019 (16.10) 也不支持这种语法。如果这样做会很好，但在那之前，您只需将 JSDoc 信息内联与属性定义混合。

在我更新了我的 vs 代码中的某些内容后，它停止了工作，我建议转移到 typescript 以获得良好的智能感知。