[Mesa-dev] [PATCH 2/3] mesa: docs: i965: Use correct doxygen groupings syntax

[Ian Romanick]

On 12/07/2015 12:18 PM, Sarah Sharp wrote:
> When reading the source code, it's useful to indicate that a group of
> fields in a struct are related in someway. The convention in Mesa seems
> to be:
> 
> struct foo {
>     /**
>      * Related fields description
>      * @{
>      */
>     int bar;
>     char baz;
>     */@}

      /*@}*/

>     long qux;
> }
> 
> However, the doxygen syntax for grouping is:
> 
> struct foo {
>     /**
>      * @defgroup group_name Related fields description

There are 193 uses of \name, but only one use @defgroup.  Assuming that
\name is also correct, and
https://www.stack.nl/~dimitri/doxygen/manual/grouping.html#memgroup
suggests that it is, we should stick with that.

If it's not correct... can a sed job convert the \name uses to \defgroup?

>      * @{
>      */
>     int bar;
>     char baz;
>     */@}

      /*@}*/

>     long qux;
> }
> 
> https://www.stack.nl/~dimitri/doxygen/manual/grouping.html
> 
> Without the group name definition, the fields don't get properly
> grouped. Instead, the group description is applied to the first field.
> You can see this in the current doxygen build, since there are no links
> to groups (doxygen calls them modules).
> 
> Fix this. Use the brw_ prefix for the group name, since I'm pretty sure
> group names are global.
> 
> Signed-off-by: Sarah Sharp <sarah.a.sharp at linux.intel.com>
> ---
>  src/mesa/drivers/dri/i965/brw_device_info.h | 12 ++++++------
>  1 file changed, 6 insertions(+), 6 deletions(-)
> 
> diff --git a/src/mesa/drivers/dri/i965/brw_device_info.h b/src/mesa/drivers/dri/i965/brw_device_info.h
> index 4911c23..89c1501 100644
> --- a/src/mesa/drivers/dri/i965/brw_device_info.h
> +++ b/src/mesa/drivers/dri/i965/brw_device_info.h
> @@ -49,8 +49,8 @@ struct brw_device_info
>     bool has_resource_streamer;
>  
>     /**
> -    * Quirks:
> -    *  @{
> +    * @defgroup brw_quirks Hardware quirks
> +    * @{
>      */
>     bool has_negative_rhw_bug;
>  
> @@ -62,11 +62,11 @@ struct brw_device_info
>      * fragment shader instructions.
>      */
>     bool needs_unlit_centroid_workaround;
> -   /** @} */
> +   /* @} */
>  
>     /**
> -    * GPU Limits:
> -    *  @{
> +    * @defgroup brw_gpu_limits GPU hardware limitations
> +    * @{
>      */
>     unsigned max_vs_threads;
>     unsigned max_hs_threads;
> @@ -83,7 +83,7 @@ struct brw_device_info
>        unsigned max_ds_entries;
>        unsigned max_gs_entries;
>     } urb;
> -   /** @} */
> +   /* @} */
>  };
>  
>  const struct brw_device_info *brw_get_device_info(int devid);
>