使用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