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

Sarah Sharp sarah.a.sharp at linux.intel.com
Mon Dec 7 12:18:31 PST 2015


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
     * @{
     */
    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);
-- 
2.3.0



More information about the mesa-dev mailing list