Question

我正在记录NodeJS + Express项目，我希望能够从JavaScript文件中引用特定的LESS视图和Jade模板。例如：

/** Displays the homepage using the {@link views/index} view. Requires {@link stylesheets/news.less} for styling the news section. */
exports.index = function(req, res){
    res.render( 'index', { title: 'Welcome' } );
};

除了能够链接到非JS文件之外，我希望它们与其他所有内容一起出现在侧边栏中。

我可以在每个.less / .jade文件中放置一个标头，并告诉JSDoc通过项目的conf.json解析它们，但是......我不希望JSDoc < em>实际上解析它们，因为那将是一团糟。

Answer 1

我通过在views.jsdoc目录中创建views文件，在stylesheets.jsdoc目录中创建stylesheets文件来解决这个问题。在.jsdoc中，我将LESS和JADE文件声明为外部，每个文件都在其自己的块注释中。例如：

<强> views.jsdoc

/**
 * The homepage view. Uses the {@link external:views/news} widget to render each news article.
 * @external views/index
 * @extends external:views/layout
 */

/**
 * The news widget.
 * @external views/news
 */

/**
 * The base layout from which all other views inherit from.
 * @external views/layout
 */

Answer 2

您可以使用JSDoc3附带的内置commentsOnly插件（但这会弄乱行号）：

// jsdoc.json
{
  "plugins": ["plugins/commentsOnly"]
}

然后jsdoc src -d docs -R README.md -c jsdoc.json

您也可以编写自己的插件来执行相同的操作，但保留换行符：

// jsdocPlugin.js
var commentPattern = /\/\*\*[\s\S]+?\*\//g,
    notNewLinePattern = /[^\n]/g,
    extname = require('path').extname,
    extension = '.js',
    comments;

exports.handlers = {
  beforeParse: function (e) {
    if (extension === extname(e.filename)) {
      comments = e.source.match(commentPattern);
      e.source = comments ? e.source.split(commentPattern).reduce(function(result, source, i) {
        return result + source.replace(notNewLinePattern, '') + comments[i];
      }, '') : e.source.replace(notNewLinePattern, '');
    }
  }
};

// jsdoc.json
{
  "plugins": ["jsdocPlugin.js"]
}

然后jsdoc src -d docs -R README.md -c jsdoc.json

我在JSDoc周围编写了一个小包装器，它可以执行此操作，您可以在Node.js中以编程方式使用 - Documentation

是否可以在JSDoc中描述非JavaScript文件？

2 个答案: