The udoc way of life

Life with udoc may be summed up as

Nothing for nothing, and a lot for a little.

If you write the minimum udoc needs, udoc will take your text, learn more from the code itself (e.g. that this function is a reimplementation of that function), and generate suitable documentation in several formats.

If the input is insufficient, udoc's primary task is to help you write more, by giving you the best possible pointers to where more is needed.

By contrast, a program such as doxygen tries to produce the best possible output, even if the input is lacking. Doxygen does a good job of that - it can generate ten thousand words in five different output formats based on absolutely nothing. And with graphics too. It all looks very impressive.

Put differently, udoc's goal is to support a process that results in good documentation. Udoc alone isn't enough, a process is needed. Udoc does not try to supplant that process.

If you want the result and will maintain a suitable development process, udoc may be good for you. If you don't, doxygen may be better for you. Doxygen tries to accommodate you - it won't ask you to accommodate it.

There are two big limitations that udoc users have to obey: Using classes and not using the preprocessor.

Udoc's output files are sorted according to class. Each class gets a single web page, for example. There isn't anywhere to put output for global functions. Thus, if your code isn't organized in classes, udoc's output will not describe your code well.

There is also no preprocessor in udoc, so preprocessor statements and strange comments give it hiccups. Here's the worst possible example:

void A::b( const /* yes, really const */ C * d,
#if defined(USES_MUMBLE)
           Mumble * e
#else
           void * e
#endif
                      )
{
    ….
}

At Oryx, we organize our code in classes, we don't use the preprocessor, we put some effort into ensuring that our interfaces are documented and easily understandable, and we try to keep our code ready for code review. Udoc works well for us.

If it can also work well for you, that makes us happy.

Relevant links

About this page

Last modified: 2010-05-03
Location: aox.org/udoc/philosophy