Doxydown is an utility to convert Doxygen style comments from the source code to Markdown.
Unlike other documentation systems, doxydown is specifically designed to generate Markdown output only.
At the moment, doxydown can work with C, Lua, SQL, and Perl comments and produce kramdown/pandoc or GitHub
flavoured markdown. Doxydown produces output with anchors, links and table of content.
It also can highlight syntax for examples in the documentation.
Markdown is used by many contemporary engines and can be rendered to HTML using advanced templates, styles and scripts. Markdown provides excellent formatting capabilities while it doesn't require authors to be web designers to create documentation. Markdown is rendered by GitHub so doxydown can generate documentation is easily viewed directly inside GitHub. Moreover, doxydown supports pandoc style of markdown and that means that markdown output can be converted to all formats supported by pandoc (html, pdf, latex, man pages and many others).
Doxydown is extremely simple as it can output markdown only but it is very convenient tool to generate nice Markdown with all features required from the documentation system. Doxydown uses input format that is almost identical to Goxygen that allows to you to re-use the existing documentation comments. Currenly, Doxydown does not support many features but they could be easily added on demand. The source is meant to be easily hackable and easily extended.
Doxydown extracts documentation from the comments blocks. The start of block is indicated by a comment block.
For example:
/***
* This is a C block
*/--[[[
-- This is a Lua block
--]]--[[[
-- This is a Lua SQL block
--]]
--------
-- Alternate Lua and SQL Format
--------###
# This is a Perl block
###Doxydown also strips an initial comment characters if you have used them for decoration. The following comment blocks are synatically identical...
/***
* some text
* other text
*
*//***
some text
other text
*/Note that doxydown preserves empty lines and all markdown elements.
Each documentation block describes either module or function/method. Modules are
logical compounds of functions and methods. The difference between method and
function is significant for languages with methods support (e.g. by lua via
metatables). To define method or function you can use the following:
/***
@function my_awesome_function(param1[, param2])
This function is awesome.
*/
All text met in the current documentation block is used as function or method description. You can also define parameters and return values for functions and methods:
@param {type} param1 mandatory param
Here, {type} is optional type description for a parameter, param1 is parameter's name
and the rest of the string is parameter description. Currently, you cannot split
parameter description by newline character. In future versions of doxydown this might
be fixed.
You can specify return type of your function by using of @return tag:
@return {type} some cool result
This tag is similar to @param and has the same limitation regarding newlines.
You can also add some example code by using of @example tag:
@example
my_awesome_function('hello'); // returns 42
All text after @example tag and until documentation block end is used as an example
and is highlighted in markdown. Also you can switch the language of example by using
the extended @example tag:
@example lua
In this example, the code will be highlighted as lua code.
Modules descriptions uses the same conventions, but @param and @return are
meaningless for the modules. Function and methods blocks that follows some @module
block are automatically attached to that module.
Both modules and function can use links to other functions and methods by using of
@see tag:
@see my_awesome_function
This inserts a hyperlink to the specified function definition to the markdown.
Doxydown can generate github flavoured markdown and pandoc/kramdown compatible markdown. The main difference is in how anchors are organized. In kramdown and pandoc it is possible to specify an explicit id for each header, whilst in GH flavoured markdown we can use only implicit anchors.
You can see an example of github flavoured markdown render at
libucl github page.
The same page bu rendered by kramdown engine in jekyll platform can be
accessed by this address.
doxydown [-hg] [-e language] [-l language] < input_source > markdown.md
-h: help message-e: sets default example language (default: lua)-l: sets input language (default: c)-g: use github flavoured markdown (default: kramdown/pandoc)
Doxydown is published by terms of MIT license.