From 4b120e51f15c0bc65abc6feeecc35625217da305 Mon Sep 17 00:00:00 2001 From: Victor Toso Date: Wed, 20 Apr 2022 21:08:06 +0200 Subject: [PATCH] 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 Reviewed-by: Peter Krempa --- include/libvirt/libvirt-common.h.in | 49 +++++++++++++++++++++-------- src/util/virtypedparam-public.c | 38 ++++++++++++++++++++++ 2 files changed, 74 insertions(+), 13 deletions(-) diff --git a/include/libvirt/libvirt-common.h.in b/include/libvirt/libvirt-common.h.in index 4661ee9857..fedf9765a7 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: 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 4cb54f7ab1..1aea13149f 100644 --- 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,