如何使用 JSDOC3 记录枚举常量
How To Use JSDOC3 To Document Enum Constants
我们正在使用 JSDOC 来记录我们面向客户的 SDK,但我们很难让它识别我们的 'enums'(即常量)。我们应该使用哪些标签让 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 记录这个?
在查看 this article on Whosebug 之后,我能够使用以下方法使它正常工作:
/**
* @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"
*/
我看到有评论要求对这个旧 post 进行更多说明。我只是从上面弄明白了,并且可以作为一个例子分享我的想法。登陆此页面搜索相同内容的人可能会发现这很有用。
/**
* 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
},
}
我们正在使用 JSDOC 来记录我们面向客户的 SDK,但我们很难让它识别我们的 'enums'(即常量)。我们应该使用哪些标签让 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 记录这个?
在查看 this article on Whosebug 之后,我能够使用以下方法使它正常工作:
/**
* @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"
*/
我看到有评论要求对这个旧 post 进行更多说明。我只是从上面弄明白了,并且可以作为一个例子分享我的想法。登陆此页面搜索相同内容的人可能会发现这很有用。
/**
* 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
},
}