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.sh...@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);
>
_______________________________________________
mesa-dev mailing list
mesa-dev@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/mesa-dev
