C/C++注释头为何存在冗余斜杠*//**？Doxygen配置疑问

为何选择不对称的注释格式？ #

我常看到C/C++代码里使用这种注释格式：

/**************************************************************************//**
 * 一些注释内容
 *****************************************************************************/

明明有更美观的对称格式可选：

/*****************************************************************************
 * 一些注释内容
 *****************************************************************************/

我清楚Doxygen需要特定格式的注释来生成文档，也知道可以在Doxyfile中启用JAVADOC_BLOCK选项。既然无需牺牲代码美观性就能满足需求，为什么大家还要使用前一种不对称的格式？而且不管采用哪种格式，都可以自由选择是否添加Doxygen命令。

实际配置中的意外行为 #

我尝试启用JAVADOC_BLOCK但关闭JAVADOC_AUTOBRIEF时，出现了与官方说明不符的情况——注释仍会自动生成摘要。

官方说明：若JAVADOC_AUTOBRIEF标签设为YES，Doxygen会将Javadoc风格注释的第一行（至第一个点）视为简要描述。若设为NO，Javadoc风格注释的行为将与常规Qt风格注释一致（因此需要显式@brief命令来添加简要描述。）

我基于doxygen-1.11.0版本做了如下测试：

/******************************************************************************
 *
 * \file a.c
 *
 ******************************************************************************/

/******************************************************************************
 *
 * 无brief的javadoc风格头注释
 *
 ******************************************************************************/
void a(void)
{
}  

/******************************************************************************
 *
 * \brief 带brief的javadoc风格头注释
 *
 ******************************************************************************/
void b(void)
{    
}
  
  
/**************************************************************************//**
 *
 * 无brief的doxygen风格头注释
 *
 ******************************************************************************/
void c(void)
{    
} 
 
/**************************************************************************//**
 *
 * \brief 带brief的doxygen风格头注释
 *
 ******************************************************************************/
void d(void)
{    
} 
 
int main(void)
{
    a();
    b();
    c();
    d();
    return 0;
}

测试结果显示，函数a和c的注释依然被自动生成了摘要，与预期不符。

无奈的妥协优化 #

我猜测无法按照预期配置Doxygen，只能被迫使用这种不够美观的注释风格。目前能做的最佳优化是调整星号数量，让首尾的星号对齐：

/*************************************************************************//**
 * 一些注释内容
 *****************************************************************************/

内容的提问来源于stack exchange，提问作者elechris