docstring: libvirt-common: Add 'Since version' metadata

Similarly to previous commits but with the targeting libvirt-common
in a batch.

Either create or append to existing docstring, the version (git tag)
that a given typedef, enum value, macro or function was introduced
in the format:

    Since: v1.2.3

Signed-off-by: Victor Toso <victortoso@redhat.com>
Reviewed-by: Peter Krempa <pkrempa@redhat.com>

diff --git a/include/libvirt/libvirt-common.h.in b/include/libvirt/libvirt-common.h.in
index 4661ee98574b337745aa6036446f64c05f041a08..fedf9765a7c706c258f23e0773f9839c1bd218c7 100644 (file)
--- 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: v0.0.1
  */
 
 # 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,24 @@ 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: v0.5.0
  */
 typedef void (*virFreeCallback)(void *opaque);
 
+/**
+ * virConnectCloseReason:
+ *
+ * Since: v0.10.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: v0.10.0) */
+    VIR_CONNECT_CLOSE_REASON_EOF       = 1, /* End-of-file from server (Since: v0.10.0) */
+    VIR_CONNECT_CLOSE_REASON_KEEPALIVE = 2, /* Keepalive timer triggered (Since: v0.10.0) */
+    VIR_CONNECT_CLOSE_REASON_CLIENT    = 3, /* Client requested it (Since: v0.10.0) */
 
 # ifdef VIR_ENUM_SENTINELS
-    VIR_CONNECT_CLOSE_REASON_LAST
+    VIR_CONNECT_CLOSE_REASON_LAST /* (Since: v0.10.0) */
 # endif
 } virConnectCloseReason;
 
@@ -122,18 +133,20 @@ typedef enum {
  * virTypedParameterType:
  *
  * Express the type of a virTypedParameter
+ *
+ * Since: v0.9.2
  */
 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: v0.9.2) */
+    VIR_TYPED_PARAM_UINT    = 2, /* unsigned integer case (Since: v0.9.2) */
+    VIR_TYPED_PARAM_LLONG   = 3, /* long long case (Since: v0.9.2) */
+    VIR_TYPED_PARAM_ULLONG  = 4, /* unsigned long long case (Since: v0.9.2) */
+    VIR_TYPED_PARAM_DOUBLE  = 5, /* double case (Since: v0.9.2) */
+    VIR_TYPED_PARAM_BOOLEAN = 6, /* boolean(character) case (Since: v0.9.2) */
+    VIR_TYPED_PARAM_STRING  = 7, /* string case (Since: v0.9.8) */
 
 # ifdef VIR_ENUM_SENTINELS
-    VIR_TYPED_PARAM_LAST
+    VIR_TYPED_PARAM_LAST /* (Since: v0.9.10) */
 # endif
 } virTypedParameterType;
 
@@ -143,6 +156,8 @@ typedef enum {
  * Flags related to libvirt APIs that use virTypedParameter.
  *
  * These enums should not conflict with those of virDomainModificationImpact.
+ *
+ * Since: v0.9.8
  */
 typedef enum {
     /* 1 << 0 is reserved for virDomainModificationImpact */
@@ -157,6 +172,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: v0.9.8
      */
     VIR_TYPED_PARAM_STRING_OKAY = 1 << 2,
 
@@ -166,6 +183,8 @@ typedef enum {
  * VIR_TYPED_PARAM_FIELD_LENGTH:
  *
  * Macro providing the field length of virTypedParameter name
+ *
+ * Since: v0.9.2
  */
 # define VIR_TYPED_PARAM_FIELD_LENGTH 80
 
@@ -177,6 +196,8 @@ 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 +219,8 @@ 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 4cb54f7ab157f12a24e01a72b7f4c23a85604788..1aea13149f1101133d004bb2ec4bb6bba07dff79 100644 (file)
--- a/src/util/virtypedparam-public.c
+++ b/src/util/virtypedparam-public.c
@@ -127,6 +127,8 @@ 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 +178,8 @@ 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 +216,8 @@ 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 +254,8 @@ 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 +292,8 @@ 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 +330,8 @@ 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 +368,8 @@ 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 +408,8 @@ 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 +449,8 @@ 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 +497,8 @@ 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 +545,8 @@ 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 +593,8 @@ 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 +641,8 @@ 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 +689,8 @@ 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 +739,8 @@ virTypedParamsAddBoolean(virTypedParameterPtr *params,
  * already exists in @params.
  *
  * Returns 0 on success, -1 on error.
+ *
+ * Since: v1.0.2
  */
 int
 virTypedParamsAddString(virTypedParameterPtr *params,
@@ -757,6 +787,8 @@ virTypedParamsAddString(virTypedParameterPtr *params,
  * key @name.
  *
  * Returns 0 on success, -1 on error.
+ *
+ * Since: v1.2.17
  */
 int
 virTypedParamsAddStringList(virTypedParameterPtr *params,
@@ -802,6 +834,8 @@ virTypedParamsAddStringList(virTypedParameterPtr *params,
  * exists in @params.
  *
  * Returns 0 on success, -1 on error.
+ *
+ * Since: v1.0.2
  */
 int
 virTypedParamsAddFromString(virTypedParameterPtr *params,
@@ -840,6 +874,8 @@ 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 +902,8 @@ virTypedParamsClear(virTypedParameterPtr params,
  * @params.
  *
  * Returns nothing.
+ *
+ * Since: v1.0.2
  */
 void
 virTypedParamsFree(virTypedParameterPtr params,