Customizing Doxygen html output

Question

We have a function header format that we have to follow. It basically looks like this

/**
* Name: blah
*
* Parameters:
*       int foo
*       bool bar
*
* .....

We are attempting to generate some documents with doxygen, but one issue is that when we change he code to:

/**
* Name: blah
*
* Parameters:
*  \param  int foo
*  \param  bool bar
*
* .....

When Doxygen generates the html comments, it adds the Parameters title. We are required to have line 4, so this creates documents with 2 lines that say Parameters, the first is from line 4 and the second Doxygen auto inserts.

What I'm hoping I can do is either have Doxygen ignore line 4 or add have it not insert it's own "Parameters:" title. Anyone know if this is possible?

Clifford · Accepted Answer · 2010-12-20 22:23:23Z

3

The simple solution is to remove the "Parameters:" text altogether; it is entirely redundant since the Doxygen mark-up makes it perfectly clear that they are parameters!

For that matter the "Name:" label is entirely redundant too, and forces you to place the name in both the comment and the code. Why would you need that? It's name is right there in the code. It is an unnecessary comment maintenance headache, and Doxygen will use teh name in the code not the name in the comment in the generated documentation.

If you must attempt to mix your existing format with a Doxygen compatible format it would be easier to use C++/C99 line comments rather than block comments; most C compilers support them:

// Name: blah
//
// Parameters:
/// \param  foo Description of foo
/// \param  bar Description of bar

Note \param <type> <name> is not correct Doxygen syntax; it is \param <name> <description>. Doxygen gets the type from the code; again specifying the type in the comment is entirely redundant, and another maintenance headache.

I would strongly suggest that you employ a more Doxygen and maintenance friendly function boiler-plate altogether. I use the following basic form (for what its worth):

//! @brief  Brief description
//!
//! Full description if necessary.
//! @param p1    p1 description
//! @param p2    p2 description
//! @return Return value description
int foobar( int p1, int p2 ) ;

Obviously whether you use /// or //! and \ or @ is a matter of preference.

answered Dec 20, 2010 at 22:23

Clifford

94.3k14 gold badges93 silver badges176 bronze badges

Sign up to request clarification or add additional context in comments.

5 Comments

Andy Over a year ago

I'm going to see if this is possible, but likely it'll involve too much paperwork(It's for flight worthy code), I'm sure they'll argue that they want it readable without any knowledge of Doxygen. Granted I think anyone that can make sense of the source should be able to infer what the Doxygen tags are representing.

Clifford Over a year ago

@Andy: While I believe coding standards are important, it is unfortunate that your existing standard was so poorly designed (by duplicating information that is implicit, and at least in your example providing no actual useful information not already in the code). Changing it would be for the better in the long term IMO. Of course you then have to consider what to do with all the legacy code - change it or raise a concession. If applied consistently, changing it could be scripted.

Andy Over a year ago

Was actually able to talk them into restructuring the function headers! We're using comments formatted in xml so we can parse out information into with other third party tools if necessary

Clifford Over a year ago

@Andy: Interesting; you know that Visual Studio already defines an XML comment format for documentation? It may be worth using their tags: msdn.microsoft.com/en-us/magazine/cc302121.aspx. However the problem with XML of course is the "angle bracket tax" (codinghorror.com/blog/2008/05/xml-the-angle-bracket-tax.html)

Andy Over a year ago

Yeah I did use most of the tags that visual studio defines. Doxygen picks up most of them. We did lose some readability, but I feel the advantages outweighed the disadvantages.

Collectives™ on Stack Overflow

Customizing Doxygen html output

1 Answer 1

5 Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

5 Comments

Your Answer

Sign up or log in

Post as a guest

Related