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

[Andrea Bolognani]

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.

-- 
Andrea Bolognani / Red Hat / Virtualization