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>
       */

那会在doc字符串中的任何地方插入我对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"
};

我可以在JSDOC中包含变量吗？

1 个答案: