I often see:
/**************************************************************************//**
* some comments
*****************************************************************************/
Why not:
/*****************************************************************************
* some comments
*****************************************************************************/
As I understand doxygen requires special comments to process it (see: Documenting the code). But it also has the option to enable JAVADOC_BLOCK in doxyfile. Why compromise the aesthetics of code when it's not needed? You can choose to add doxygen commands to those blocks too or leave them out if you want.
Edit: I get unexpected behavior when checking JAVADOC_BLOCK, but unchecking JAVADOC_AUTOBRIEF. It still autobriefs.
If the JAVADOC_AUTOBRIEF tag is set to YES then doxygen will interpret the first line (until the first dot) of a Javadoc-style comment as the brief description. If set to NO, the Javadoc-style will behave just like regular Qt- style comments (thus requiring an explicit @brief command for a brief description.)[emphasis mine]
/******************************************************************************
*
* \file a.c
*
******************************************************************************/
/******************************************************************************
*
* javadoc header without brief
*
******************************************************************************/
void a(void)
{
}
/******************************************************************************
*
* \brief javadoc header with brief
*
******************************************************************************/
void b(void)
{
}
/**************************************************************************//**
*
* doxystyle header without brief
*
******************************************************************************/
void c(void)
{
}
/**************************************************************************//**
*
* \brief doxystyle header with brief
*
******************************************************************************/
void d(void)
{
}
int main(void)
{
a();
b();
c();
d();
return 0;
}
In doxygen-1.11.0 a and c autobrief
Edit2: I guess doxygen cannot be configured the way I want it. I'm forced to use their aestheticially unpleasing comment styles. The best improvement I could make is to use this (notice the asterisks at the end align now):
/*************************************************************************//**
* some comments
*****************************************************************************/
Sometimes one wants to put a big separator comment in the source code just to break the source code up.
For example, if you have a collection of related structures (or c++ classes) in a single header file (because you like big header files), you might consider inserting a big banner comment that tells the reader that "This is the main class", or "these are all the internal structures". Remember that in c you don't have the same flexibility to hide utility structures inside the objects that use them.
You just don't want that comment to go into the generated documentation file if it will add nothing to the documentation.
Other times, you want the big banner style in the file, but then you decide you do want the content in the generated documentation file, because it has added some value. Sometimes this is a later editorial decision.
Of course, you can also use javadoc tags to generate sections in the documentation which you could use to collate related internal structures, and you could use the existing banners to do that - or not, it is a choice, sometimes born out of not wanting to overcomplicate the generated documentation.
The /***************************// trick lets you choose on an individual basis to promote some banners to the documentation, while ignoring most of them, and not reformatting your source file too much.