[v2,11/14] kernel-doc: public/version.h

Commit Message

Stefano Stabellini Oct. 21, 2020, midnight UTC

Convert in-code comments to kernel-doc format wherever possible.

Signed-off-by: Stefano Stabellini <[e-mail]>
---
Changes in v2:
- remove "- XENVER_{version,pagesize}"
---
 xen/include/public/version.h | 73 +++++++++++++++++++++++++++++-------
 1 file changed, 59 insertions(+), 14 deletions(-)

Comments

Jan Beulich Oct. 23, 2020, 10:02 a.m. UTC | #1

On 21.10.2020 02:00, Stefano Stabellini wrote:
> --- a/xen/include/public/version.h
> +++ b/xen/include/public/version.h
> @@ -30,19 +30,32 @@
>  
>  #include "xen.h"
>  
> -/* NB. All ops return zero on success, except XENVER_{version,pagesize}
> - * XENVER_{version,pagesize,build_id} */
> +/**
> + * DOC: XENVER_*
> + *
> + * NB. All ops return zero on success, except for:
> + *
> + * - XENVER_{version,pagesize,build_id}
> + */
>  
> -/* arg == NULL; returns major:minor (16:16). */
> +/**
> + * DOC: XENVER_version
> + * @arg == NULL; returns major:minor (16:16).
> + */
>  #define XENVER_version      0
>  
> -/* arg == xen_extraversion_t. */
> +/**
> + * DOC: XENVER_extraversion
> + * @arg == xen_extraversion_t.
> + */
>  #define XENVER_extraversion 1
>  typedef char xen_extraversion_t[16];
>  #define XEN_EXTRAVERSION_LEN (sizeof(xen_extraversion_t))
>  
> -/* arg == xen_compile_info_t. */
>  #define XENVER_compile_info 2
> +/**
> + * struct xen_compile_info - XENVER_compile_info
> + */

At the example of this one - elsewhere I think I've seen you also
use single-line comments starting with /**. I can accept the choice
of multi-line here, but I think I'd like ./CODING_STYLE to then be
amended to allow such in certain cases.

Jan

Patch

diff --git a/xen/include/public/version.h b/xen/include/public/version.h
index 17a81e23cd..47bb04961e 100644
--- a/xen/include/public/version.h
+++ b/xen/include/public/version.h
@@ -30,19 +30,32 @@ 
 
 #include "xen.h"
 
-/* NB. All ops return zero on success, except XENVER_{version,pagesize}
- * XENVER_{version,pagesize,build_id} */
+/**
+ * DOC: XENVER_*
+ *
+ * NB. All ops return zero on success, except for:
+ *
+ * - XENVER_{version,pagesize,build_id}
+ */
 
-/* arg == NULL; returns major:minor (16:16). */
+/**
+ * DOC: XENVER_version
+ * @arg == NULL; returns major:minor (16:16).
+ */
 #define XENVER_version      0
 
-/* arg == xen_extraversion_t. */
+/**
+ * DOC: XENVER_extraversion
+ * @arg == xen_extraversion_t.
+ */
 #define XENVER_extraversion 1
 typedef char xen_extraversion_t[16];
 #define XEN_EXTRAVERSION_LEN (sizeof(xen_extraversion_t))
 
-/* arg == xen_compile_info_t. */
 #define XENVER_compile_info 2
+/**
+ * struct xen_compile_info - XENVER_compile_info
+ */
 struct xen_compile_info {
     char compiler[64];
     char compile_by[16];
@@ -51,52 +64,84 @@  struct xen_compile_info {
 };
 typedef struct xen_compile_info xen_compile_info_t;
 
+/**
+ * DOC: XENVER_capabilities
+ * @arg: xen_capabilities_info_t
+ */
 #define XENVER_capabilities 3
 typedef char xen_capabilities_info_t[1024];
 #define XEN_CAPABILITIES_INFO_LEN (sizeof(xen_capabilities_info_t))
 
+/**
+ * DOC: XENVER_changeset
+ * @arg: xen_changeset_info_t
+ */
 #define XENVER_changeset 4
 typedef char xen_changeset_info_t[64];
 #define XEN_CHANGESET_INFO_LEN (sizeof(xen_changeset_info_t))
 
 #define XENVER_platform_parameters 5
+/**
+ * struct xen_platform_parameters - XENVER_platform_parameters
+ */
 struct xen_platform_parameters {
     xen_ulong_t virt_start;
 };
 typedef struct xen_platform_parameters xen_platform_parameters_t;
 
 #define XENVER_get_features 6
+/**
+ * struct xen_feature_info - XENVER_get_features
+ */
 struct xen_feature_info {
-    unsigned int submap_idx;    /* IN: which 32-bit submap to return */
-    uint32_t     submap;        /* OUT: 32-bit submap */
+    /** @submap_idx: IN: which 32-bit submap to return */
+    unsigned int submap_idx;
+    /** @submap: OUT: 32-bit submap */
+    uint32_t     submap;
 };
 typedef struct xen_feature_info xen_feature_info_t;
 
-/* Declares the features reported by XENVER_get_features. */
+/**
+ * DOC: features.h
+ * Declares the features reported by XENVER_get_features.
+ */
 #include "features.h"
 
-/* arg == NULL; returns host memory page size. */
+/**
+ * DOC: XENVER_pagesize
+ * @arg == NULL; returns host memory page size.
+ */
 #define XENVER_pagesize 7
 
-/* arg == xen_domain_handle_t.
+/**
+ * DOC: XENVER_guest_handle
+ *
+ * @arg == xen_domain_handle_t.
  *
  * The toolstack fills it out for guest consumption. It is intended to hold
  * the UUID of the guest.
  */
 #define XENVER_guest_handle 8
 
+/**
+ * DOC: XENVER_commandline
+ * @arg: xen_commandline_t
+ */
 #define XENVER_commandline 9
 typedef char xen_commandline_t[1024];
 
-/*
+#define XENVER_build_id 10
+/**
+ * struct xen_build_id - XENVER_build_id
+ *
  * Return value is the number of bytes written, or XEN_Exx on error.
  * Calling with empty parameter returns the size of build_id.
  */
-#define XENVER_build_id 10
 struct xen_build_id {
-        uint32_t        len; /* IN: size of buf[]. */
+        /** @len: IN: size of buf[]. */
+        uint32_t        len;
+        /** @buf: OUT: Variable length buffer with build_id. */
         unsigned char   buf[XEN_FLEX_ARRAY_DIM];
-                             /* OUT: Variable length buffer with build_id. */
 };
 typedef struct xen_build_id xen_build_id_t;