Is it possible to describe non-JavaScript files in JSDoc?

Problem

I'm documenting a NodeJS + Express project and I'd like to be able to reference specific LESS views and Jade templates from the JavaScript files. For example:

/** 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' } );
};

In addition to being able to link to non-JS files, I would like for them to appear in the sidebar along with everything else.

I could just put a header in every .less/.jade file and tell JSDoc to parse them through the project's conf.json, but... I don't want JSDoc to actually parse them because that would be a mess.

Problem courtesy of: jSepia

Solution

I got around this by creating a views.jsdoc file inside my views directory, and a stylesheets.jsdoc file inside my stylesheets directory. In the .jsdocs, I declared my LESS and JADE files as externals, each in its own block comment. Example:

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
 */
Solution courtesy of: jSepia

Discussion

You can use the built in commentsOnly plugin that ships with JSDoc3 (though, that messes up line numbers):

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

and then jsdoc src -d docs -R README.md -c jsdoc.json


You could also write your own plugin that does the same thing, but preserves newlines:

// 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"]
}

and then jsdoc src -d docs -R README.md -c jsdoc.json


I wrote a small wrapper around JSDoc, that does this and you can use programmatically in Node.js - Documentation

Discussion courtesy of: Eugene Kuzmenko

This recipe can be found in it's original form on Stack Over Flow.