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

【问题标题】：Is it possible to describe non-JavaScript files in JSDoc?是否可以在 JSDoc 中描述非 JavaScript 文件？
【发布时间】：2015-12-31 23:14:52
【问题描述】：

我正在记录一个 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 实际上 解析它们，因为那会是一团糟。

【问题讨论】：

标签： node.js express jsdoc

【解决方案1】：

我通过在我的views 目录中创建一个views.jsdoc 文件和在我的stylesheets 目录中的一个stylesheets.jsdoc 文件来解决这个问题。在.jsdocs 中，我将我的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
 */

【讨论】：

【解决方案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

【讨论】：