[PATCH v2 07/14] kernel-doc: public/hypfs.h

[Stefano Stabellini <sstabellini@xxxxxxxxxx>]

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

Signed-off-by: Stefano Stabellini <stefano.stabellini@xxxxxxxxxx>
---
 xen/include/public/hypfs.h | 72 ++++++++++++++++++++++++--------------
 1 file changed, 45 insertions(+), 27 deletions(-)

diff --git a/xen/include/public/hypfs.h b/xen/include/public/hypfs.h
index 2b7a66d68d..62a33a1646 100644
--- a/xen/include/public/hypfs.h
+++ b/xen/include/public/hypfs.h
@@ -32,12 +32,21 @@
  * Definitions for the __HYPERVISOR_hypfs_op hypercall.
  */
 
-/* Highest version number of the hypfs interface currently defined. */
+/**
+ * DOC: XEN_HYPFS_VERSION
+ * Highest version number of the hypfs interface currently defined.
+ */
 #define XEN_HYPFS_VERSION      1
 
-/* Maximum length of a path in the filesystem. */
+/**
+ * DOC: XEN_HYPFS_MAX_PATHLEN
+ * Maximum length of a path in the filesystem.
+ */
 #define XEN_HYPFS_MAX_PATHLEN  1024
 
+/**
+ * struct xen_hypfs_direntry
+ */
 struct xen_hypfs_direntry {
     uint8_t type;
 #define XEN_HYPFS_TYPE_DIR     0
@@ -49,17 +58,23 @@ struct xen_hypfs_direntry {
     uint8_t encoding;
 #define XEN_HYPFS_ENC_PLAIN    0
 #define XEN_HYPFS_ENC_GZIP     1
-    uint16_t pad;              /* Returned as 0. */
-    uint32_t content_len;      /* Current length of data. */
-    uint32_t max_write_len;    /* Max. length for writes (0 if read-only). */
+    /** @pad: Returned as 0. */
+    uint16_t pad;
+    /** @content_len: Current length of data. */
+    uint32_t content_len;
+    /** @max_write_len: Max. length for writes (0 if read-only). */
+    uint32_t max_write_len;
 };
 typedef struct xen_hypfs_direntry xen_hypfs_direntry_t;
 
+/**
+ * struct xen_hypfs_dirlistentry
+ */
 struct xen_hypfs_dirlistentry {
     xen_hypfs_direntry_t e;
-    /* Offset in bytes to next entry (0 == this is the last entry). */
+    /** @off_next: Offset in bytes to next entry (0 == this is the last 
entry). */
     uint16_t off_next;
-    /* Zero terminated entry name, possibly with some padding for alignment. */
+    /** @name: Zero terminated entry name, possibly with some padding for 
alignment. */
     char name[XEN_FLEX_ARRAY_DIM];
 };
 
@@ -67,21 +82,22 @@ struct xen_hypfs_dirlistentry {
  * Hypercall operations.
  */
 
-/*
- * XEN_HYPFS_OP_get_version
+/**
+ * DOC: XEN_HYPFS_OP_get_version
  *
  * Read highest interface version supported by the hypervisor.
  *
  * arg1 - arg4: all 0/NULL
  *
  * Possible return values:
- * >0: highest supported interface version
- * <0: negative Xen errno value
+ *
+ * - >0: highest supported interface version
+ * - <0: negative Xen errno value
  */
 #define XEN_HYPFS_OP_get_version     0
 
-/*
- * XEN_HYPFS_OP_read
+/**
+ * DOC: XEN_HYPFS_OP_read
  *
  * Read a filesystem entry.
  *
@@ -96,19 +112,20 @@ struct xen_hypfs_dirlistentry {
  * The contents of a directory are multiple struct xen_hypfs_dirlistentry
  * items.
  *
- * arg1: XEN_GUEST_HANDLE(path name)
- * arg2: length of path name (including trailing zero byte)
- * arg3: XEN_GUEST_HANDLE(data buffer written by hypervisor)
- * arg4: data buffer size
+ * - arg1: XEN_GUEST_HANDLE(path name)
+ * - arg2: length of path name (including trailing zero byte)
+ * - arg3: XEN_GUEST_HANDLE(data buffer written by hypervisor)
+ * - arg4: data buffer size
  *
  * Possible return values:
- * 0: success
- * <0 : negative Xen errno value
+ *
+ * - 0: success
+ * - <0 : negative Xen errno value
  */
 #define XEN_HYPFS_OP_read              1
 
-/*
- * XEN_HYPFS_OP_write_contents
+/**
+ * DOC: XEN_HYPFS_OP_write_contents
  *
  * Write contents of a filesystem entry.
  *
@@ -116,14 +133,15 @@ struct xen_hypfs_dirlistentry {
  * The data type and encoding can't be changed. The size can be changed only
  * for blobs and strings.
  *
- * arg1: XEN_GUEST_HANDLE(path name)
- * arg2: length of path name (including trailing zero byte)
- * arg3: XEN_GUEST_HANDLE(content buffer read by hypervisor)
- * arg4: content buffer size
+ * - arg1: XEN_GUEST_HANDLE(path name)
+ * - arg2: length of path name (including trailing zero byte)
+ * - arg3: XEN_GUEST_HANDLE(content buffer read by hypervisor)
+ * - arg4: content buffer size
  *
  * Possible return values:
- * 0: success
- * <0 : negative Xen errno value
+ *
+ * - 0: success
+ * - <0: negative Xen errno value
  */
 #define XEN_HYPFS_OP_write_contents    2
 
-- 
2.17.1