GitHub: Render markdown in code comments / docblock?

Question

Let's say I have a javascript file in github, and add some markdown to a comment block:

/**
 * # Markdown here?
 * - list?
 * */
function MyClass(){
  this.someMethod = function(){
    // this method is added to each new instance
    // for this reason, adding your methods here can bloat
  };  
}

Can I get doc-blocks or comment blocks to render as markdown?

Answer 1

No, that's not possible.

However, you could create an external documentation using a tool like Sphinx - while it doesn't use markdown it uses ReStructured Text which is somewhat similar.

Answer 2

There are multiple documentation tools to scrape source code comments for Markdown. Each tool requires the comments to be written in certain format and some are more strict than others. Here is a couple of examples:

Yamdog parses Markdown and YAML from JavaScript modules and uses the following syntax:

// mylib.myfun(foo, options)
//
// My function with some *general* documentation.
//
// Parameters:
//   foo
//     string that does something.
//   options
//     optional object with properties:
//     - bar
//         optional string. Default `barval`.
//     - baz
//         optional number that does a thing and
//         ..then some more. Default `bazval`.
//
// Return:
//   integer, the number of bars
//

Markdox uses Dox parser to read JsDoc and Markdown from JavaScript with the following syntax:

/**
 * My function with some *general* documentation.
 *
 * @function mylib.myfun
 * @param {string} foo String that does something.
 * @param {object} options Optional object with properties.
 * @param {string} options.bar Optional string. Default 'barval'.
 * @param {number} options.baz Optional number that does
 * - a thing and then some more. Default 'bazval'.
 *
 * @returns {integer} The number of bars.
 */

While Yamdog has relaxed and minimal syntax, Markdox and JsDoc in general use various tags to clearly define what is being documented. Some like the freedom, others prefer strict and powerful definitions. Personally I prefer my comments to look like text, not like code. Disclaimer: I am the maintainer of Yamdog.

Other related tools:

• JSDuck uses syntax similar to Dox. The project seems to be abandoned.
• Docco - generate documents where the code is literally embedded between Markdown found in comments.