Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Documentation generation program

branch: master
README.md

DocThis! Documentation Generator

This program converts definition files to HTML and/or LaTeX files. The format of the definition files are similar to markdown, with some features removed, some tweaked and some added. A thorough explanation on the format can be found in the file doc/format which can itself be compiled with DocThis!.

In the test/test* folders there is a Makefile which is typically what you would have to write (or copy-paste-modify) that takes documentation sources from the folder definitions and compiles them. The output would be in generated/html and generated/tex folders. In the test/test*/definitions folders, there can be found documentation on projects I wrote.

There are a few reasons why I wrote this program and don't use doxygen:

  • The file names doxygen creates is a mess. I am not an expert in doxygen, but I reckon cross-referencing from explanation of one function to explanation of the others is not easy.

  • With doxygen you mix code and documentation. This is terrible for a few reasons

    • You are discouraged to write complete (and thus long) documentations. This is because your code gets cluttered with documentation and moving around the code becomes a pain.

    • As is seen in numerous projects, the documentation and the code are not matched, yet this remains undetected. The reason for this is that, since the documentation is next to the code, it is assumed to be up-to-date by doxygen. Since the programmer doesn't always remember to mark the comment above the function as "outdated", the programmer himself would also forget what needs to be updated. Outdated documentation is very hard to detect when using doxygen.

  • You can't read the documentation if you are in a system that doesn't have a browser or PDF viewer.

The good points about DocThis! are these:

  • The html and tex file names are similar to the definition files and anchors are made based on the variable/type/function/etc name. So you easily create a link in the description of some element to another part of the documentation

  • The documentation looks like what you want and contains what you tell it to.

  • The output is customizable. There is a .css file (more themes to be added in the future) that can be used if the user so desires.

  • It creates one output file per input file and thus, except the file containing list of globals, it doesn't need to regenerate the whole documentation on every build, but it would only do so for updated files (see the Makefile that is included)

  • With the DocThis! syntax, you can style your documentation without having to code HTML.

  • The documentation and the code are apart (opposite of the negative point of doxygen as I already explained). DocThis! requires you to provide the version number for the program/library as meta data of each page individually. As the code progresses, versions change and outdated documentation pages are instantly identified.

  • The source files of the documentation are good-looking documentations themselves! So if you found yourself coding on a light linux that doesn't have a GUI, you can simply refer to the documentation source files. The syntax of DocThis! is designed specially to simplify links and make them understandable.

  • DocThis! requires you to have explanation, even if short, on everything. You cannot for example leave explanation of a function argument empty. Often it happens that some arguments seems obvious to the programmer, leaving it undocumented only to cause confusion later for the user. Not with DocThis!

The bad points are these:

  • You need to write more than doxygen. One reason is that the things that are automatically done in doxygen, such as your function prototype need to be done manually here because DocThis! doesn't inspect your code. This is however as small as identifier declarations and a small header.

I found the best way for documenting using DocThis! is this. Have a Changelog file, whenever you change something put in there and mark it as changed but not documented. Then, every once in a while that you want a break, go to the documentation, update something and mark it in the Changelog as reflected in the documentation. This way, you always have your documentation up-to-date or only slightly behind.

Something went wrong with that request. Please try again.