[PATCH v2 02/34] docs: variable: Move docstring from source to header file

[Peter Krempa]

On Thu, Apr 14, 2022 at 22:47:13 +0200, Victor Toso wrote:
> virConnectAuthPtrDefault is the only variable that we export and with
> the documentation being at the C file, it makes harder to find it.
> 
> With this patch, the documentation of this variable can be found by
> those who look at the header file for guidance plus, it will also be
> included in the XML API, as the followup patch will fix apibuild.py
> to store what is documented in the header file for this variable.
> 
> Note that the apibuild, does not do the same with .c files. It'd
> require adding it for (parsing) recursion, similar to what is done for
> functions.  Considering the pros/cons, seems more reasonable to move
> the docstring to the header file instead.
> 
> Signed-off-by: Victor Toso <victortoso at redhat.com>
> ---
>  include/libvirt/libvirt-host.h | 13 +++++++++++++
>  src/libvirt.c                  | 11 +----------
>  2 files changed, 14 insertions(+), 10 deletions(-)
> 
> diff --git a/include/libvirt/libvirt-host.h b/include/libvirt/libvirt-host.h
> index 1dc4b8a147..8081d9e39d 100644
> --- a/include/libvirt/libvirt-host.h
> +++ b/include/libvirt/libvirt-host.h
> @@ -562,6 +562,19 @@ struct _virConnectAuth {
>  typedef struct _virConnectAuth virConnectAuth;
>  typedef virConnectAuth *virConnectAuthPtr;
>  
> +/*
> + * virConnectAuthPtrDefault:
> + *
> + * A default implementation of the authentication callbacks. This
> + * implementation is suitable for command line based tools. It will
> + * prompt for username, passwords, realm and one time keys as needed.
> + * It will print on STDOUT, and read from STDIN. If this is not
> + * suitable for the application's needs an alternative implementation
> + * should be provided.
> + *
> + * Since: v1.0.0

This seems to be added by commit v0.3.3-120-g7fa9ceb740