::

Docu

I'm always trying to write clean and understandable code in my projects, but saying that I always manage to do that is by far an exaggeration.

One thing that it helps me a lot to keep the code "clean" is to make it open source and to maintain a documentation of it.
But I always felt the mainstream documentation tools unnecessary complex, full of features that I would never use, or with too much feature that makes the whole documentation job boring and slow.

But I always felt the mainstream documentation tools unnecessary complex, full of features that I would never use, or with too much feature that makes the whole documentation job boring and slow.

So one day I tought: what if I build my own documentation tool from scratch with C99? And I did it.

The concept

With Docu I wanted to make something extremly simple that reads special comments in the code, parse all the information into a data structure, and then let you choose to export that data structure into various format (printing in console, HTML, Emacs Org Mode, etc).

The core part of Docu is the parsing of the information of a function declaration to get all the information possible automatically. This works well when using it on descriptive languages like C, a little less well with something more compact like Lisp.

When Gisp can't retrieve some data (like a parameter type of a function in Lisp) the programmer can provide it to Docu using other special comments.

Internally Docu organize the functions data into modules to further organize the informations. Modules can also be defined with special comments.

The extras and plans

The core part that parse the code into data is driven by special configuration files that defines how Docu should read the functions through some regex. So to add new languages I only need to make the right regex and make the configuration file for it.

The plan is to add the most popular languages configuration file and add other renderer formats to export the data.

An example

If you want to see an example, Gisp documentation is currently generated through Docu and is hosted on this website here: Gisp Documentation