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

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.