Some thoughts on doxygen usage

tools

Thought I am going to state some things about doxygen usage, lets say 3 things for today.

Documentation location

Lets call this in-source vs out-of-source.

In-source documentation

In short, in-source documentation is writing the doxygen comments on top of function or class declarations.
The documentation is along the source code.

Out-of-source documentation

Writing documentation out-of-source means that the documentation is in a different file than the declarations.
Some people like that, since they find that it keeps the code clean, what is from some point of view OK, I guess.

In case of a C/C++ project this means that if you have a file pair foo.h and foo.cpp that you have to create an extra text file, say foo.doxy, which will contain all the doxygen documentations for whatever you want to document from foo.h/cpp.

My thoughts on in-source vs out-of-source documentation

I prefer in-source documentation over out-of-source documentation and here are some reasons why:

  • The only pro argument I heard so far for out-of-source documentation is to keep the code clean.
    To me, keeping the code clean from documentation sounds already wrong.

  • Writing documentation not beside the documented elements means that you need to specify what to document over and over again. This means the usage of extra tags for the element you document. These extra tags need to stay in sync with the code, what is extra work.
    This is redundant information and together with the extra work it makes refactoring much harder.
    Writing documentation should not make anything harder, it should make things simpler.

  • It is nice that, when writing a function call in C or C++ , to jump to the definition of a function and find the corespondent documentation there. This of course requires your IDE or editor to support jumping to a definition.
    Every IDE or editor that’s worth to use supports this functionality.

  • Modern IDEs have the possibility to show documentation found to a method on mouse over of a method call.
    This is very nice.

  • For this to work it basically means that the documentation for public functions need to be written into the header files. If done so developers do not need to leave their editor/IDEs to look up the documentation for a class or method.
    Everything is available at fingertip, very convenient.

  • Out of source documentation forces users that are interested in the documentation to open some external tool for reading the documentation, like a browser of pdf reader.
    A lot of people do not like to leave their IDE or editor if it’s not required. I am one of them.
    People should be allowed to use what ever tool they want to read the documentation.

Doing in-source documentation wrong

There are project that manage to do in-source documentation combined the disadvantages of out-of-source documentation.

How does this work?

Write your public documentation not to the declarations, (header files) but rather into the source files.
This does of course not fully work, for example for enum declarations or class declarations.
For documenting these elements you need to decide between:

a) be inconsistent with your decision to write documentation in source files and write some documentation into the header files.
or
b) make out of source documentation for these elements, with all it’s disadvantages, in the source files

I think this is a bad idea, especially for a public interface. For me, internal or private documentation in source files is ok but not the public interfaces.
I would not want to disable some features like IDE integration or reading the documentation in ones favorite editor for no other reason than just because.

Asking people why they put the documentation for the public interfaces into the source files it turns out there is no reason.
Or no other reason than to have some delimiter between functions.
I am not convinced that this is the right motivation.

The \file and \author tags in doxygen file documentation

The first 2 tags in a doxygen documentation are very often the \file and the \author tags.

Lets have a look at them.

Using of the \file tags

The usage of \file tag together with the file name in in-source documentation is useless and redundant information.

foo.h
/**
 * \file foo.h
 *
 */

Doxygen is smart enough to know the file it is processing, so adding redundant information like this is not just useless. It also prevents some people from renaming files because updating the tags is 'too much work' and they prefer therefore to stick with badly named files. I am not joking, this happened in a project I worked with.

So the \file tag is a required and necessary for out of source documentation, but not required for in-source documentation,

You might what to have a look at the STRIP_FROM_PATH configuration variable to generate nice file names without using the \file tag.

Apropos filenames, there is also a STRIP_FROM_INC_PATH configuration variable.

The \author tag

Often, after the \file tag, the author tag is the next one in a doxygen file header.

You know about some legacy code where you find the name of authors in the source code that have left the project or company years ago, don’t you?

Well this happens, and if this is ugly code people do not really like to update the \author information after several buxfixes and changes in the code.

The worst is, that an \author tag can motivate people to not feel responsible for source code.

You know someone has edited such a file, but when ask about what’s going on in the code the response is something like: "oh, this was written by John Doe, yea, horrible, I don’t really know …​"

Avoid the author tags, they might become reasons for wrong excuses.
There has to be a version control for such information like who has edited which files.

This does not mean that you do not have any copyright info

doxygen has a \copyright tag, you might want to use this

Usage of none for \param and \return in function documentation

Now this one might be a little bit special since it affects just one project I worked with, but I have also seen this in some open source projects where I looked at the code, so I thought this is the right place and moment to release my thoughts about that.

This one might also be a little bit C++ specific.

Let’s have a look at this.

class Foo {
public:

 /**
 * \brief: Constructor,
 * Initialize default values ....
 * \param none
 * \return none
 */
 class Foo();

};

There are 2 things from which I don’t get why it should be specified since it is obvious and doxygen can figure them out without any help.

  • \param none
    I know there have been some problems with f(void) constructs, but this would be C and should not exist in C++.
    So for a programming language that does not take any number of arguments without specify them this seems to make no sense.

  • \return none
    I do not even have a theoretical explanation why someone could think that this makes sense. Maybe in script languages that use to return the result of the last executed statement, but for C++?

Your comments are appreciated

Have you ever seen something like \param none or \return none and do you know why it would be a good idea to do so?

Do you use the \file and the \author tag and plan continue to use them?

Are you having any thoughts about in-source vs out-of-source documentation?

If you have any thoughts or answers to my questions, or if you have found some typos in my text, feel free to use the comment function below.