javascript - 使用 jsdoc 创建自定义标签

Question

我正在尝试在 jsdoc 3.4.2 中创建自定义标签。 config.json 文件是

{
    "tags": {
        "allowUnknownTags": true,
        "dictionaries": ["jsdoc","closure"]
    },

    "source": {
        "include": [
            "app/"
            ],
        "exclude": [],
        "includePattern": ".+\\.js(doc|x)?$",
        "excludePattern": "(^|\\/|\\\\)_"
    },
    "plugins": [
        "plugins/custom-tags.js"
        ],
    "templates": {
        "cleverLinks": false,
        "monospaceLinks": false
    },
    "opts": {
        "destination": "./docs",
        "recurse": true,
        "encoding": "utf8"
    }
}

在 custom-tags.js 我添加了这些行

exports.defineTags = function (dictionary) {
    dictionary.defineTag("service", {
        mustHaveValue: true,
        canHaveType: false,
        canHaveName: true,
        onTagged: function (doclet, tag) {
            doclet.service = tag.value;
        }
    });
}; 

但是当我在代码中使用@service 时，它​​没有显示。我查看了一些与此相关的链接，发现我们需要创建模板的自定义标签，但没有找到创建模板的方法。我已经在我的 Windows 机器上全局安装了 jsdoc。

Answer 1

你是对的，有两个步骤。

• 首先，您为 jsdoc 定义一个标签以在代码中查找并更新其 doclet 对象(就像您所做的那样)
• 其次，您需要模板，将 doclet 对象转换为 HTML，以了解新属性并使用它执行某些操作。

和您一样，我也很难找到有关制作模板的说明。我能建议的最好的方法是检查 jsdoc 源代码。您需要创建一个公开 publish 函数的 JavaScript 文件。 publish 函数将遍历 doclet 对象以生成 HTML。

我和你有同样的需求，但我只想在现有的 jsdoc 模板中添加一个新部分(标题和文本可能是一个参数表)。我真的不想为此创建一个全新的模板，所以我最终定义了我的标签，它们最终会将 HTML 附加到 doclet.description 属性。为我工作。

exports.defineTags = function(dictionary) {
    dictionary.defineTag('routeparam', {
        mustHaveValue: true,
        mustNotHaveDescription: false,
        canHaveType: true,
        canHaveName: true,
        onTagged: function(doclet, tag) {
            if (!doclet.routeparams) {
              doclet.routeparams = [];
            }

            doclet.routeparams.push({
              'name': tag.value.name,
              'type': tag.value.type ? (tag.value.type.names.length === 1 ? tag.value.type.names[0] : tag.value.type.names) : '',
              'description': tag.value.description || '',
            });
        }
    });
};

exports.handlers = {
  newDoclet: function(e) {
    const parameters = e.doclet.routeparams;
    if (parameters) {
      const table = tableBuilder.build('Route Parameters', parameters);

      e.doclet.description = `${e.doclet.description}
                              ${table}`;
    }
  }
}

请随时查看我的存储库，看看我是如何做到的 https://github.com/bvanderlaan/jsdoc-route-plugin