Возможно ли описать файлы без JavaScript в JSDoc?

Question

Я документирую проект NodeJS + Express, и я хотел бы иметь возможность ссылаться на определенные виды LESS и шаблоны Jade из файлов JavaScript. Например:

/** 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 к фактически разобрать их, потому что это будет бардак.

Answer 1

Я получил вокруг этого, создавая views.jsdoc файл в моем views директории, и stylesheets.jsdoc файл в моем stylesheets каталоге. В .jsdoc s я объявлял свои файлы 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

Вы можете использовать встроенный в commentsOnly плагин, который поставляется с JSDoc3 (хотя, что путает номера строки):

// 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