[PATCH v2 00/34] Add 'version' to other exported types

[Victor Toso]

Hi,

The goal of this patch series is to provide 'since' version to all
exported types.

This is the non lazy version of the v1. In this series, we do
change the docstrings of all exported types, to add the version
metadata, in order to have scripts/apibuild.py to fetch it and add
it to the appropriated XML API. This patch series also enforces
that every new exported types requires a docstring with version
with the proper format.

  v1: https://listman.redhat.com/archives/libvir-list/2022-April/229881.html

I've created a script that helped me out and it covered a good
amound of cases. I hand fixes all the missing docstrings and
corner cases that my script missed.

As mentioned in v1, I've used:

    git grep -rq $symbol $tag $includedir

This is used to find if a given $symbol exists in a given $tag or
not. $tag starts with v1.0.0 and I have ignored any $tag that does
not start with 'v' or has '-rc' in the name.

To help review this not so small changeset, the changes were split
in the following order:

 * docs: generated: 98% work from the script. I've split it
                    further, by module + group type.

 * docs: manual: -> 30% manual labor, 70% vim's macro. It was also
                    split where it seems reasonable.

 * docs: (...) -> Some fixes needed in the docs.

 * scripts: -> Improvements to apibuild script.

 * syms: -> Some fixes found with the found mismatch between
            docstring and sym files.

Other than that, I only caught two false positives, that is, a $symbol
was present in a $tag but it was exported only at a latter $tag.

Branch  : https://gitlab.com/victortoso/libvirt/-/commits/add-since-version
Green CI: https://gitlab.com/victortoso/libvirt/-/pipelines/517262280

Cheers,
Victor

Victor Toso (34):
  docs: Fix generated documentation of virConnectListAllNodeDeviceFlags
  docs: variable: Move docstring from source to header file
  docs: generated: enums: libvirt: append 'Since version' metadata
  docs: generated: enums: qemu: append 'Since version' metadata
  docs: generated: enums: admin: append 'Since version' metadata
  docs: generated: macros: libvirt: append 'Since version' metadata
  docs: generated: macros: admin: append 'Since version' metadata
  docs: generated: typedefs: libvirt: append 'Since version' metadata
  docs: generated: typedefs: qemu: append 'Since version' metadata
  docs: generated: typedefs: admin: append 'Since version' metadata
  docs: generated: functions: libvirt: append 'Since version' metadata
  docs: generated: functions: qemu: append 'Since version' metadata
  docs: generated: functions: lxc: append 'Since version' metadata
  docs: generated: functions: admin: append 'Since version' metadata
  docs: manual: typedef: add docstring and Since metadata
  docs: manual: functions: add Since metadata
  docs: manual: enums: add docstring and Since metadata
  docs: manual: macros: add docstring and Since metadata
  docs: manual: libvirt-common: add docstring and Since metadata
  docs: Fix generated documentation of virStorageVolInfoFlags
  docs: Fix and append Since to virConnectListAllStoragePoolsFlags
  docs: Fix and append Since to virDomainDeviceModifyFlags
  docs: Fix and append Since to virDomainMemoryModFlags
  docs: Fix and append Since to virDomainVcpuFlags
  scripts: apibuild: parse 'Since' version for enums
  scripts: apibuild: fix parsing block comments from typedef enum
  scripts: apibuild: parse 'Since' for typedefs
  scripts: apibuild: parse 'Since' for macros
  scripts: apibuild: parse 'Since' for functions
  scripts: apibuild: factor out comment cleaning
  scripts: apibuild: add parsing variable's comments
  syms: admin: Add sections to match when API was introduced
  syms: libvirt: move virDomainSetBlockThreshold to 3.2.0
  syntax-check: sc_prohibit_nonreentrant: skip comments

 build-aux/syntax-check.mk                   |    2 +-
 include/libvirt/libvirt-admin.h             |   95 +-
 include/libvirt/libvirt-common.h.in         |   54 +-
 include/libvirt/libvirt-domain-checkpoint.h |   62 +-
 include/libvirt/libvirt-domain-snapshot.h   |  100 +-
 include/libvirt/libvirt-domain.h            | 2665 +++++++++++++++----
 include/libvirt/libvirt-event.h             |   35 +-
 include/libvirt/libvirt-host.h              |  320 ++-
 include/libvirt/libvirt-interface.h         |   33 +-
 include/libvirt/libvirt-network.h           |  195 +-
 include/libvirt/libvirt-nodedev.h           |  100 +-
 include/libvirt/libvirt-nwfilter.h          |   29 +-
 include/libvirt/libvirt-qemu.h              |   39 +-
 include/libvirt/libvirt-secret.h            |   81 +-
 include/libvirt/libvirt-storage.h           |  316 ++-
 include/libvirt/libvirt-stream.h            |   48 +-
 include/libvirt/virterror.h                 |  428 +--
 scripts/apibuild.py                         |  136 +-
 src/admin/libvirt-admin.c                   |   93 +
 src/admin/libvirt_admin_public.syms         |   58 +-
 src/libvirt-domain-checkpoint.c             |   36 +
 src/libvirt-domain-snapshot.c               |   63 +
 src/libvirt-domain.c                        |  557 +++-
 src/libvirt-host.c                          |  102 +
 src/libvirt-interface.c                     |   63 +
 src/libvirt-lxc.c                           |   12 +
 src/libvirt-network.c                       |  135 +
 src/libvirt-nodedev.c                       |   81 +
 src/libvirt-nwfilter.c                      |   72 +
 src/libvirt-qemu.c                          |   18 +
 src/libvirt-secret.c                        |   60 +
 src/libvirt-storage.c                       |  171 ++
 src/libvirt-stream.c                        |   51 +
 src/libvirt.c                               |   29 +-
 src/libvirt_public.syms                     |    8 +-
 src/util/virerror.c                         |   45 +
 src/util/virevent.c                         |   27 +
 src/util/virtypedparam-public.c             |   57 +
 38 files changed, 5317 insertions(+), 1159 deletions(-)

-- 
2.35.1