如何使用JSDOC3记录枚举常量

Question

我们正在使用JSDOC记录我们的客户端SDK，并且我们很难让它识别我们的“枚举”（即常量）。我们应该使用哪些标签来让JSDOC在文档中捕获它？以下是一份示例：

/**
* @module Enum
*/
export namespace {

    /**
    * @enum WidgetType {string}
    */
    Enum.WidgetType = {
        /** Dashboard */
        Dashboard: 'dashboard',
        /** Form */
        Form: 'entityeditform',
        /** Report */
        Report: 'report'
    };
}

以下是“enums”在代码中的使用方式：

枚举类型在代码中的用法如下：

app.widget({ id: 'account_entityform', type: Enum.WidgetType.Form }).add();

我们如何使用JSDOC进行文档记录？

- A2MetalCore

Answer 1

我看到这篇旧文章有评论要求更多解释。我从以上内容中找到了答案，可以分享一个例子，希望搜索同样问题的人会发现这个例子有用。

/**
 * The color of a piece or square.
 * @readonly
 * @enum {number}
 * @property {number} WHITE color for a white square or piece.
 * @property {number} BLACK color for a black square or piece.
 */
export const Color = { WHITE: 0, BLACK: 1 }

/** 
 * Each member is an enumeration of direction offsets used to index into the 
 * lists of horzontal, vertical, and diagonal squares radiating from a
 * given Square object. Only useful internally for initialization or externally
 * for test.
 * @package
 * @type {object}
 * @readonly
 * @property {enum} Cross an enumeration of vert and horiz directions.
 * @property {number} Cross.NORTH north
 * @property {number} Cross.EAST  east
 * @property {number} Cross.SOUTH south
 * @property {number} Cross.WEST  west
 * @property {enum} Diagonal an enumeration of diagonal directions.
 * @property {number} Diagonal.NORTHEAST northeast
 * @property {number} Diagonal.SOUTHEAST southeast
 * @property {number} Diagonal.SOUTHWEST southwest
 * @property {number} Diagonal.NORTHWEST northwest
 */
const Direction = {
    Cross: { 
        NORTH: 0, EAST: 1, SOUTH: 2, WEST: 3 
    },
    Diagonal: { 
        NORTHEAST: 0, SOUTHEAST: 1, SOUTHWEST: 2, NORTHWEST: 3 
    },
}

- Todd

---

只读（Readonly）不能像那样工作，不幸的是，你必须将它附加到对象内的每个属性。 - basickarl

我注意到JS文档导向工具对上述格式的支持不一致。因此，它可能适用于某些工具，但对其他工具则不适用。@basickarl - Todd

Answer 2

在浏览这篇StackOverflow文章后，我使用以下方法使其正常工作：

    /**
    * @typedef FieldType
    * @property {string} Text "text"
    * @property {string} Date "date"
    * @property {string} DateTime "datetime"
    * @property {string} Number "number"
    * @property {string} Currency "currency"
    * @property {string} CheckBox "checkbox"
    * @property {string} ComboBox "combobox"
    * @property {string} Dropdownlist "dropdownlist"
    * @property {string} Label "label"
    * @property {string} TextArea "textarea"
    * @property {string} JsonEditor "jsoneditor"
    * @property {string} NoteEditor "noteeditor"
    * @property {string} ScriptEditor "scripteditor"
    * @property {string} SqlEditor "sqleditor"
    */

- A2MetalCore

---

有点不太清楚，因为你的回答与原问题中的代码片段不相符。 - Zlatin Zlatev

@ASA2，我目前也遇到了同样的问题；不过，我还不太理解你的例子。能否详细解释一下并提供一个完整的例子呢？这将非常友善。 - j3141592653589793238