[PATCH v2 19/34] docs: manual: libvirt-common: add docstring and Since metadata

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



This commit adds Since metadata to the libvirt-common's macros,
enums and functions.

Signed-off-by: Victor Toso <victortoso@xxxxxxxxxx>
---
 include/libvirt/libvirt-common.h.in | 54 ++++++++++++++++++++-------
 src/util/virtypedparam-public.c     | 57 +++++++++++++++++++++++++++++
 2 files changed, 98 insertions(+), 13 deletions(-)

diff --git a/include/libvirt/libvirt-common.h.in b/include/libvirt/libvirt-common.h.in
index 4661ee9857..ba0a44351e 100644
--- a/include/libvirt/libvirt-common.h.in
+++ b/include/libvirt/libvirt-common.h.in
@@ -70,6 +70,8 @@ extern "C" {
  *
  * Macro providing the version of the library as
  * version * 1,000,000 + minor * 1000 + micro
+ *
+ * Since: v1.0.0
  */
 
 # define LIBVIR_VERSION_NUMBER @LIBVIRT_VERSION_NUMBER@
@@ -86,6 +88,8 @@ extern "C" {
  *   #if LIBVIR_CHECK_VERSION(1,1,3)
  *     // some code that only works in 1.1.3 and newer
  *   #endif
+ *
+ * Since: v1.2.0
  */
 # define LIBVIR_CHECK_VERSION(major, minor, micro) \
     ((major) * 1000000 + (minor) * 1000 + (micro) <= LIBVIR_VERSION_NUMBER)
@@ -104,17 +108,26 @@ extern "C" {
  * from a context which is not re-entrant safe. Failure to
  * abide by this requirement may lead to application deadlocks
  * or crashes.
+ *
+ * Since: v1.0.0
+ *
  */
 typedef void (*virFreeCallback)(void *opaque);
 
+/**
+ * virConnectCloseReason:
+ *
+ * Since: v1.0.0
+ *
+ */
 typedef enum {
-    VIR_CONNECT_CLOSE_REASON_ERROR     = 0, /* Misc I/O error */
-    VIR_CONNECT_CLOSE_REASON_EOF       = 1, /* End-of-file from server */
-    VIR_CONNECT_CLOSE_REASON_KEEPALIVE = 2, /* Keepalive timer triggered */
-    VIR_CONNECT_CLOSE_REASON_CLIENT    = 3, /* Client requested it */
+    VIR_CONNECT_CLOSE_REASON_ERROR     = 0, /* Misc I/O error (Since: v1.0.0) */
+    VIR_CONNECT_CLOSE_REASON_EOF       = 1, /* End-of-file from server (Since: v1.0.0) */
+    VIR_CONNECT_CLOSE_REASON_KEEPALIVE = 2, /* Keepalive timer triggered (Since: v1.0.0) */
+    VIR_CONNECT_CLOSE_REASON_CLIENT    = 3, /* Client requested it (Since: v1.0.0) */
 
 # ifdef VIR_ENUM_SENTINELS
-    VIR_CONNECT_CLOSE_REASON_LAST
+    VIR_CONNECT_CLOSE_REASON_LAST /* (Since: v1.0.0) */
 # endif
 } virConnectCloseReason;
 
@@ -122,18 +135,20 @@ typedef enum {
  * virTypedParameterType:
  *
  * Express the type of a virTypedParameter
+ *
+ * Since: v1.0.0
  */
 typedef enum {
-    VIR_TYPED_PARAM_INT     = 1, /* integer case */
-    VIR_TYPED_PARAM_UINT    = 2, /* unsigned integer case */
-    VIR_TYPED_PARAM_LLONG   = 3, /* long long case */
-    VIR_TYPED_PARAM_ULLONG  = 4, /* unsigned long long case */
-    VIR_TYPED_PARAM_DOUBLE  = 5, /* double case */
-    VIR_TYPED_PARAM_BOOLEAN = 6, /* boolean(character) case */
-    VIR_TYPED_PARAM_STRING  = 7, /* string case */
+    VIR_TYPED_PARAM_INT     = 1, /* integer case (Since: v1.0.0) */
+    VIR_TYPED_PARAM_UINT    = 2, /* unsigned integer case (Since: v1.0.0) */
+    VIR_TYPED_PARAM_LLONG   = 3, /* long long case (Since: v1.0.0) */
+    VIR_TYPED_PARAM_ULLONG  = 4, /* unsigned long long case (Since: v1.0.0) */
+    VIR_TYPED_PARAM_DOUBLE  = 5, /* double case (Since: v1.0.0) */
+    VIR_TYPED_PARAM_BOOLEAN = 6, /* boolean(character) case (Since: v1.0.0) */
+    VIR_TYPED_PARAM_STRING  = 7, /* string case (Since: v1.0.0) */
 
 # ifdef VIR_ENUM_SENTINELS
-    VIR_TYPED_PARAM_LAST
+    VIR_TYPED_PARAM_LAST /* (Since: v1.0.0) */
 # endif
 } virTypedParameterType;
 
@@ -143,6 +158,8 @@ typedef enum {
  * Flags related to libvirt APIs that use virTypedParameter.
  *
  * These enums should not conflict with those of virDomainModificationImpact.
+ *
+ * Since: v1.0.0
  */
 typedef enum {
     /* 1 << 0 is reserved for virDomainModificationImpact */
@@ -157,6 +174,8 @@ typedef enum {
      * the user does not have to worry about it; however, manually
      * setting the flag can be used to reject servers that cannot
      * return typed strings, even if no strings would be returned.
+     *
+     * Since: v1.0.0
      */
     VIR_TYPED_PARAM_STRING_OKAY = 1 << 2,
 
@@ -166,6 +185,9 @@ typedef enum {
  * VIR_TYPED_PARAM_FIELD_LENGTH:
  *
  * Macro providing the field length of virTypedParameter name
+ *
+ * Since: v1.0.0
+ *
  */
 # define VIR_TYPED_PARAM_FIELD_LENGTH 80
 
@@ -177,6 +199,9 @@ typedef enum {
  * The types virSchedParameter, virBlkioParameter, and
  * virMemoryParameter are aliases of this type, for use when
  * targeting libvirt earlier than 0.9.2.
+ *
+ * Since: v0.9.2
+ *
  */
 typedef struct _virTypedParameter virTypedParameter;
 
@@ -198,6 +223,9 @@ struct _virTypedParameter {
  * virTypedParameterPtr:
  *
  * a pointer to a virTypedParameter structure.
+ *
+ * Since: v0.9.2
+ *
  */
 typedef virTypedParameter *virTypedParameterPtr;
 
diff --git a/src/util/virtypedparam-public.c b/src/util/virtypedparam-public.c
index 4cb54f7ab1..2e213f2ace 100644
--- a/src/util/virtypedparam-public.c
+++ b/src/util/virtypedparam-public.c
@@ -127,6 +127,9 @@ virTypedParameterAssignFromStr(virTypedParameterPtr param,
  *
  * Returns pointer to the parameter or NULL if it does not exist in @params.
  * This function does not raise an error, even when returning NULL.
+ *
+ * Since: v1.0.2
+ *
  */
 virTypedParameterPtr
 virTypedParamsGet(virTypedParameterPtr params,
@@ -176,6 +179,9 @@ virTypedParamsGet(virTypedParameterPtr params,
  *
  * Returns 1 on success, 0 when the parameter does not exist in @params, or
  * -1 on error.
+ *
+ * Since: v1.0.2
+ *
  */
 int
 virTypedParamsGetInt(virTypedParameterPtr params,
@@ -212,6 +218,9 @@ virTypedParamsGetInt(virTypedParameterPtr params,
  *
  * Returns 1 on success, 0 when the parameter does not exist in @params, or
  * -1 on error.
+ *
+ * Since: v1.0.2
+ *
  */
 int
 virTypedParamsGetUInt(virTypedParameterPtr params,
@@ -248,6 +257,9 @@ virTypedParamsGetUInt(virTypedParameterPtr params,
  *
  * Returns 1 on success, 0 when the parameter does not exist in @params, or
  * -1 on error.
+ *
+ * Since: v1.0.2
+ *
  */
 int
 virTypedParamsGetLLong(virTypedParameterPtr params,
@@ -284,6 +296,9 @@ virTypedParamsGetLLong(virTypedParameterPtr params,
  *
  * Returns 1 on success, 0 when the parameter does not exist in @params, or
  * -1 on error.
+ *
+ * Since: v1.0.2
+ *
  */
 int
 virTypedParamsGetULLong(virTypedParameterPtr params,
@@ -320,6 +335,9 @@ virTypedParamsGetULLong(virTypedParameterPtr params,
  *
  * Returns 1 on success, 0 when the parameter does not exist in @params, or
  * -1 on error.
+ *
+ * Since: v1.0.2
+ *
  */
 int
 virTypedParamsGetDouble(virTypedParameterPtr params,
@@ -356,6 +374,9 @@ virTypedParamsGetDouble(virTypedParameterPtr params,
  *
  * Returns 1 on success, 0 when the parameter does not exist in @params, or
  * -1 on error.
+ *
+ * Since: v1.0.2
+ *
  */
 int
 virTypedParamsGetBoolean(virTypedParameterPtr params,
@@ -394,6 +415,9 @@ virTypedParamsGetBoolean(virTypedParameterPtr params,
  *
  * Returns 1 on success, 0 when the parameter does not exist in @params, or
  * -1 on error.
+ *
+ * Since: v1.0.2
+ *
  */
 int
 virTypedParamsGetString(virTypedParameterPtr params,
@@ -433,6 +457,9 @@ virTypedParamsGetString(virTypedParameterPtr params,
  * if the parameter already exists in @params.
  *
  * Returns 0 on success, -1 on error.
+ *
+ * Since: v1.0.2
+ *
  */
 int
 virTypedParamsAddInt(virTypedParameterPtr *params,
@@ -479,6 +506,9 @@ virTypedParamsAddInt(virTypedParameterPtr *params,
  * error if the parameter already exists in @params.
  *
  * Returns 0 on success, -1 on error.
+ *
+ * Since: v1.0.2
+ *
  */
 int
 virTypedParamsAddUInt(virTypedParameterPtr *params,
@@ -525,6 +555,9 @@ virTypedParamsAddUInt(virTypedParameterPtr *params,
  * error if the parameter already exists in @params.
  *
  * Returns 0 on success, -1 on error.
+ *
+ * Since: v1.0.2
+ *
  */
 int
 virTypedParamsAddLLong(virTypedParameterPtr *params,
@@ -571,6 +604,9 @@ virTypedParamsAddLLong(virTypedParameterPtr *params,
  * error if the parameter already exists in @params.
  *
  * Returns 0 on success, -1 on error.
+ *
+ * Since: v1.0.2
+ *
  */
 int
 virTypedParamsAddULLong(virTypedParameterPtr *params,
@@ -617,6 +653,9 @@ virTypedParamsAddULLong(virTypedParameterPtr *params,
  * error if the parameter already exists in @params.
  *
  * Returns 0 on success, -1 on error.
+ *
+ * Since: v1.0.2
+ *
  */
 int
 virTypedParamsAddDouble(virTypedParameterPtr *params,
@@ -663,6 +702,9 @@ virTypedParamsAddDouble(virTypedParameterPtr *params,
  * error if the parameter already exists in @params.
  *
  * Returns 0 on success, -1 on error.
+ *
+ * Since: v1.0.2
+ *
  */
 int
 virTypedParamsAddBoolean(virTypedParameterPtr *params,
@@ -711,6 +753,9 @@ virTypedParamsAddBoolean(virTypedParameterPtr *params,
  * already exists in @params.
  *
  * Returns 0 on success, -1 on error.
+ *
+ * Since: v1.0.2
+ *
  */
 int
 virTypedParamsAddString(virTypedParameterPtr *params,
@@ -757,6 +802,9 @@ virTypedParamsAddString(virTypedParameterPtr *params,
  * key @name.
  *
  * Returns 0 on success, -1 on error.
+ *
+ * Since: v1.2.17
+ *
  */
 int
 virTypedParamsAddStringList(virTypedParameterPtr *params,
@@ -802,6 +850,9 @@ virTypedParamsAddStringList(virTypedParameterPtr *params,
  * exists in @params.
  *
  * Returns 0 on success, -1 on error.
+ *
+ * Since: v1.0.2
+ *
  */
 int
 virTypedParamsAddFromString(virTypedParameterPtr *params,
@@ -840,6 +891,9 @@ virTypedParamsAddFromString(virTypedParameterPtr *params,
  * is not freed; use virTypedParamsFree if you want it to be freed too.
  *
  * Returns nothing.
+ *
+ * Since: v1.0.2
+ *
  */
 void
 virTypedParamsClear(virTypedParameterPtr params,
@@ -866,6 +920,9 @@ virTypedParamsClear(virTypedParameterPtr params,
  * @params.
  *
  * Returns nothing.
+ *
+ * Since: v1.0.2
+ *
  */
 void
 virTypedParamsFree(virTypedParameterPtr params,
-- 
2.35.1




[Index of Archives]     [Virt Tools]     [Libvirt Users]     [Lib OS Info]     [Fedora Users]     [Fedora Desktop]     [Fedora SELinux]     [Big List of Linux Books]     [Yosemite News]     [KDE Users]     [Fedora Tools]

  Powered by Linux