Re: [PATCH] docs: fix documentation of enum constants

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



On 07/20/2017 08:21 PM, Tomáš Golembiovský wrote:
> The documentation string has to follow the definition of a constant in
> the enum. Otherwise, the HTML documentation will be generated
> incorrectly.
> 
> Signed-off-by: Tomáš Golembiovský <tgolembi@xxxxxxxxxx>
> ---
>  include/libvirt/libvirt-domain.h | 62 ++++++++++++++++++++--------------------
>  1 file changed, 31 insertions(+), 31 deletions(-)
> 
> diff --git a/include/libvirt/libvirt-domain.h b/include/libvirt/libvirt-domain.h
> index 45f939a8c..2f3162d0f 100644
> --- a/include/libvirt/libvirt-domain.h
> +++ b/include/libvirt/libvirt-domain.h
> @@ -583,56 +583,56 @@ typedef virDomainInterfaceStatsStruct *virDomainInterfaceStatsPtr;
>   * Memory Statistics Tags:
>   */
>  typedef enum {
> -    /* The total amount of data read from swap space (in kB). */
>      VIR_DOMAIN_MEMORY_STAT_SWAP_IN         = 0,
> -    /* The total amount of memory written out to swap space (in kB). */
> +    /* The total amount of data read from swap space (in kB). */
>      VIR_DOMAIN_MEMORY_STAT_SWAP_OUT        = 1,
> +    /* The total amount of memory written out to swap space (in kB). */

While this fixes generated HTML, it messes up the header file. So if
somebody is looking directly into header file they might get confused.
The problem is in our doc generator. I recall this being discussed
somewhere recently (probably on the list?). The proper fix IMO is to fix
the generator so that it accepts both:

enum {
  /* Some very long description - therefore it's before the value. */
  VIR_ENUM_A_VAL = 0,
} virEnumA;

enum {
  VIR_ENUM_B_VAL = 0, /* Short description */
} virEnumB;


Michal

--
libvir-list mailing list
libvir-list@xxxxxxxxxx
https://www.redhat.com/mailman/listinfo/libvir-list




[Index of Archives]     [Virt Tools]     [Libvirt Users]     [Lib OS Info]     [Fedora Users]     [Fedora Desktop]     [Fedora SELinux]     [Big List of Linux Books]     [Yosemite News]     [KDE Users]     [Fedora Tools]
  Powered by Linux