我可以在 JSDOC 中有变量吗

Question

我有几个函数共享一些底层数据结构，同时也做非常不同的事情，这样抽象并不是一个好主意。

文档可能如下所示（尽管这只是一个小示例，许多方法仅共享此文档的一部分）：

/**
 * Creates an array of objects, with each object containing the average distance that minute. The
 * objects have the keys **Timestamp** (ms since epoch), **Year** (year in device local time) **Month** (
 * month in device local time), **Day** (day in device local time), **Hour** (hour in device local time)
 * **Season** (season in device local time, Northern Hemisphere), **Weekday** (Week day name in device
 * local time), **WeekNum** (week number (1-53) in device local time), **Depth** (the average depth that
 * minute), and **Vibration** (the magnitude of the maximum acceleration for the minute, in Gs).
 * <snip>
 */

/**
 * Creates an array of objects, with each object containing the data for one minute of temperature data
 * from temperature probes. The objects have the keys **Timestamp** (ms since epoch), **Year** (year in
 * device local time) **Month** (month in device local time), **Day** (day in device local time), **Hour**
 * (hour in device local time) **Season** (season in device local time, Northern Hemisphere), **Weekday**
 * (Week day name in device local time), **WeekNum** (week number (1-53) in device local time),
 * **Temperature** (Temperature measured by the temperature probe), **Vib**(the standard deviation of the
 * acceleration of the accelerometer, in Gs).
 * <snip>
 */

从样本中可以看出，我对振动的记录及其含义是不一致的。我不想每次更改它的含义时都去修复 6 个位置的文档（或者更糟糕的是，硬件工程师更改了它的含义）。有没有办法让我拥有一个全球术语词典并根据需要插入它？比如：

terms.json
    > {vibDef: "the magnitude of the maximum acceleration for the minute, in Gs"}

code.js
    > /**
       * Creates an array of objects, with each object containing the average distance that minute. The
       * objects have the keys **Timestamp** (ms since epoch), **Year** (year in device local time) **Month** (
       * month in device local time), **Day** (day in device local time), **Hour** (hour in device local time)
       * **Season** (season in device local time, Northern Hemisphere), **Weekday** (Week day name in device
       * local time), **WeekNum** (week number (1-53) in device local time), **Depth** (the average depth that
       * minute), and **Vibration** (<<vibDef>>).
       * <snip>
       */

这会在文档字符串中找到的任何地方插入我对 vibDef 的定义？

Answer 1

感谢@ssube 的建议，我编写了一个插件，将!> 和<! 之间的文本写入扩展为更长的定义，保存在一个全局文件中。为了记录，这里是：

var globalDict = require('../globals.js').jsDoc;


exports.handlers = {
    beforeParse: function(e) {
        var reg = /!>(?=\S)(\w+)(?=\S)<!/;
        do {
            m = reg.exec(e.source);
            if (m) {
                var originalTxt = m[0];
                var expandedDef = globalDict[m[1]];
                if (expandedDef) {
                    e.source = e.source.replace(originalTxt, expandedDef);
                } else {
                    e.source = e.source.replace(originalTxt, m[1]); // Prevent infinite loop
                    console.log('Error: Missing definition for jsDoc keyword', m[1]);
                }
            }
        } while (m);
    }
};

globals.js 看起来像：

exports.jsDoc = {
    vibration: "twice the standard deviation in the recorded acceleration over the course of a minute"
};