[PATCH v2 19/34] docs: manual: libvirt-common: add docstring and Since metadata
Victor Toso
victortoso at redhat.com
Thu Apr 14 20:47:30 UTC 2022
This commit adds Since metadata to the libvirt-common's macros,
enums and functions.
Signed-off-by: Victor Toso <victortoso at redhat.com>
---
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
More information about the libvir-list
mailing list