Re: [PATCH v3 16/30] docstring: function: admin: Add 'Since version' metadata
On Wed, Apr 20, 2022 at 21:08:05 +0200, Victor Toso wrote:
Either create or append to existing docstring, the version (git tag)
that a given function was introduced in the format:
Since: v1.2.3
Signed-off-by: Victor Toso <victortoso(a)redhat.com>
---
include/libvirt/libvirt-admin.h | 3 ++
src/admin/libvirt-admin.c | 93 +++++++++++++++++++++++++++++++++
2 files changed, 96 insertions(+)
diff --git a/include/libvirt/libvirt-admin.h b/include/libvirt/libvirt-admin.h
index c73cf6e7da..5945fc172c 100644
--- a/include/libvirt/libvirt-admin.h
+++ b/include/libvirt/libvirt-admin.h
[...]
@@ -346,6 +358,9 @@ virAdmConnectRef(virAdmConnectPtr conn)
* instead.
*
* Returns 0 on success, -1 in case of an error.
+ *
+ * Since: v1.3.0
+ *
*/
int
virAdmGetVersion(unsigned long long *libVer)
Per Daniels reply, all of these were made available only in
libvirt-2.0.0 thus at the date the symbol was published, so also the
Since tag should say so, even when the code was added previously.
The logic should be that the Since tag for function should be
MAX_VERSION(version_of_symbol, version_when_code_was_actually_added)
Thus if code was added previously but exported later, it makes no sense
to state it worked in the older version.
Similarly if symbol is exported mistakenly in a prior version but added
later it simply won't work with the older version.
Thus for the admin commands we have both situations, here it's so that
the code was added first and exposed later.
The other case is virAdmServerUpdateTlsFiles which was mistakenly added
to the LIBVIRT_2.0.0 symbol but really added in libvirt-6.2.