Problem description

CONTRIBUTING.md states a preference for /*! over /**. However, the former breaks Doxygen's autobrief feature. See, for example, documentation of the C++ SolutionArray class, where in the list of "public member functions" many instances of @brief documentation are not shown (i.e. the docstring is not broken at the dot '.'). The supported autobrief version should use /** per Doxygen documentation.

Per documentation, this works:

/** Brief description which ends at this dot. Details follow
 *  here.
 */

as well as

//! Brief description, which is
//! really a detailed description since it spans multiple lines.
/*! Another detailed description!
 */

While Doxygen is flexible, we apparently recommended a version that doesn't support autobrief, i.e.

/*! 
 * This is a detailed description. Autobrief does not work 
 * for this documentation style.
 */

I verified that this would work (although it is somewhat ugly):

//! Brief description.
/**
 * Detailed description. [...]
 */

As an aside, this is also true:

//! This is a brief description. It continues after the dot.

System information

• Cantera version: main
• OS: any
• Python/MATLAB/other software versions: doxygen=1.9.1