Inline documentation format

[Mark Constable]

> > The most used one is doxygen.
> > And I verified it can generate any other type of
> > common documents format (Latex, html, pdf, etc..)
>
> Sure, and I prefer doxygen myself. However, some may
> consider it bloated.

Just a super simple suggestion that is probably not
appropriate but FWIW. I use this format with a mildly
preprocessed Markdown (ie; showdown.js + node or gromjs)
script that simply adds ^4 spaces between the ***/ /***
sections then removes the /*** and ***/ lines then passes
it to regular Mardown code which turns it into HTML with
the code sections within <pre><code>...</code></pre>.

Advantages are it's super simple and lightweight, allows
for free form documentation, leaves /** ... */ jsdoc-like
comments in place for further processing, and once the
result is in HTML format there are a number of other
utilities to turn it into other formats like PDF. I don't
rate *nix man pages as useful enough to bother but there
are probably tools to do that conversion as well (from HTML).

/***
# Heading

## Sub-heading

* list item 1
* list item 2

This is a paragraph, etc
***/

program ... code

/***
* Author: etc
* Version: etc
* Copyright: etc
***/


--markc