[PATCH v2 03/34] docs: generated: enums: libvirt: append 'Since version' metadata

[Victor Toso]

Hi,

On Tue, Apr 19, 2022 at 06:37:19AM -0700, Andrea Bolognani wrote:
> On Tue, Apr 19, 2022 at 03:30:12PM +0200, Peter Krempa wrote:
> > On Tue, Apr 19, 2022 at 15:17:07 +0200, Victor Toso wrote:
> > > On Tue, Apr 19, 2022 at 02:40:05PM +0200, Peter Krempa wrote:
> > > > On Thu, Apr 14, 2022 at 22:47:14 +0200, Victor Toso wrote:
> > > > >  typedef enum {
> > > > >      VIR_DOMAIN_RUNNING_UNKNOWN = 0,
> > > > > -    VIR_DOMAIN_RUNNING_BOOTED = 1,          /* normal startup from boot */
> > > > > -    VIR_DOMAIN_RUNNING_MIGRATED = 2,        /* migrated from another host */
> > > > > -    VIR_DOMAIN_RUNNING_RESTORED = 3,        /* restored from a state file */
> > > > > -    VIR_DOMAIN_RUNNING_FROM_SNAPSHOT = 4,   /* restored from snapshot */
> > > > > -    VIR_DOMAIN_RUNNING_UNPAUSED = 5,        /* returned from paused state */
> > > > > -    VIR_DOMAIN_RUNNING_MIGRATION_CANCELED = 6,  /* returned from migration */
> > > > > -    VIR_DOMAIN_RUNNING_SAVE_CANCELED = 7,   /* returned from failed save process */
> > > > > +    VIR_DOMAIN_RUNNING_BOOTED = 1,          /* normal startup from boot (Since: v1.0.0) */
> > > > > +    VIR_DOMAIN_RUNNING_MIGRATED = 2,        /* migrated from another host (Since: v1.0.0) */
> > > >
> > > > Your script doesn't seem to handle well versions prior to
> > > > v1.0.0. This specific constant was added in commit
> > > > v0.9.1-133-gd65a924b34 thus it should be 'Since v0.9.2'.
> > >
> > > I actually followed the suggestion to started with v1.0.0. I can
> > > change it to work with the exact tags that it would first appear
> > > in libvirt if you think it is necessary. CC'ing Andrea for input.
> >
> > I have no problem with adding an arbitrary cut-off. It just must be
> > clear that it's from an older version, thus 'Since: v1.0.0' must not be
> > used in such case.
> >
> > > > I understand that we might not want to deal with too old
> > > > releases, but in such case we should rather pick a different
> > > > marker meaning that the symbol was added too long ago.
> > >
> > > Since v1.0.0 is not wrong if it was introduced before v1.0.0. It
> > > is just a criteria for adding the version metadata for too old
> > > releases, after the fact.
> >
> > It is not wrong but misleading in the context of other tags
> > where we have the exact version when it was introduced. Thus
> > if you change it to make it obvious that it's from an older
> > version I have no problems with that.
> 
> Sorry, I was probably not clear when I initially suggested this :(
> 
> What I wanted to express was that we could *potentially* avoid
> showing version information for symbols that were introduced in
> v1.0.0 and earlier *in the generated HTML documentation* if it
> turns out that always showing this information results in too
> much clutter.
> 
> I agree with Peter that we should record accurate version
> information in the header files.

No problem. I'll change to add the correct version for all <
1.0.0.

Cheers,
Victor
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: not available
URL: <http://listman.redhat.com/archives/libvir-list/attachments/20220419/064ed4d5/attachment.sig>