有没有可能在JSDoc中描述非JavaScript文件？

我logging了一个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来parsing它们，但是…我不想让JSDoc 真正parsing它们，因为那样会很乱。

Answer 1

我通过在我的views目录中创build一个views.jsdoc文件，以及我的stylesheets目录下的一个stylesheets.jsdoc文件来解决这个问题。 在.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插件（尽pipe这会混淆行号）：

 // 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中使用编程方式 – 文档