使用jsdoc创建自定义标记 [英] create custom tags with jsdoc

问题描述

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

I am trying to create custom tags in jsdoc 3.4.2. The config.json file is

{
    "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。

But when i used the @service in the code, it is not showing. I had looked some link relating this and found out for custom tags we need to create template, but not found a way of creating one. I had installed jsdoc globally on my windows machine.

推荐答案

你说得对，有两个步骤。

You are correct there is a two step process.

• 首先为代码中的jsdoc定义一个标签并更新其 doclet 对象（就像你一样）已经完成了）


• 其次你需要模板，将 doclet 对象转换成HTML，以了解新属性和用它做点什么。

• First you define a tag for jsdoc to find in the code and update its doclet object (like you have done)
• Second you need the template, the thing which turns the doclet object into HTML, to know about the new property and do something with it.

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

Like you I've had a hard time finding instructions on making templates. The best I can suggest is check the jsdoc source code. You'll need to create a JavaScript file which exposes a publish function. The publish function will then iterate over the doclet object to generate HTML.

我有与你相同的需求，但我想做的就是在现有的jsdoc模板中添加一个新的部分（标题和文本可能是一个参数表）。我真的不想为此创建一个全新的模板，所以我最终定义了我的标签，他们最终将HTML附加或添加到 doclet.description 财产。为我工作。

I had the same need as you but all I wanted to do was add a new section (header and text maybe a table of parameters) to the existing jsdoc template. I didn't really want to go and create a whole new template just for that so I ended up defining my tags in a way that they would end up appending or prepending HTML to the doclet.description property. Worked for me.

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}`;
    }
  }
}

随时查看我的repo看我是怎么做的 https://github.com/bvanderlaan/jsdoc-route-plugin

Feel free to check out my repo to see how I did it https://github.com/bvanderlaan/jsdoc-route-plugin

这篇关于使用jsdoc创建自定义标记的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！