Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

Any software to auto generate doxygen comment blocks?

Tags:

c++

doxygen

I'm developing a large C++ program and I've now decided to document it with Doxygen. There are plenty of classes, methods, functions, macros and so on. Therefore I'm searching for software that would scan my source tree and insert Doxygen comment blocks on top of every "documentable item" to let me edit them later and add details such as method descriptions and so on.

Does any such software exist?

I'm under GNU/Linux with the Code::Blocks IDE, so no Visual Studio plugins are needed.

like image 348
Simone Margaritelli Avatar asked Mar 26 '10 16:03

Simone Margaritelli


1 Answers

I am quite perplex here.

What is the goal of automatically generating comments ?

Comments are meant to bring additional value:

/**
 * \brief: finds the person based on its name
 * \param: name, the name of the person
 * \result: the person
 */
Person findPerson(Name name);

Is nothing but code clutter that clog my valuable screen estate. And that's about as much as can be generated automatically unfortunately... Notice in particular that I have no idea of what happens if ever the function does not find the person, which certainly seems likely: does it abort ? throws ? (what... ?) returns a default constructed object ?

On the other hand:

///
/// Try an exact match approach to begin with
/// Uses the double metaphone algorithm
///   if none was found as we have
///   a western european clientele
///
Person findPerson(Name name)
{
}

is much more interesting!

  • Now I know what is this strange collection of if that seems to be performing some kind of sound recognition...
  • I know its name so I can look it up on Internet to check its implementation (functionality)
  • And I know why it was selected and thus when I should reevaluate its use (fits a western european clientele so if we develop on arabic market it'll need adaptation...)

Unfortunately, that's not going to be generated automatically.

like image 59
Matthieu M. Avatar answered Sep 18 '22 16:09

Matthieu M.