[PATCH v4 00/19] Add 'version' to other exported types

[Andrea Bolognani]

On Tue, Apr 26, 2022 at 06:26:26PM +0200, Victor Toso wrote:
> On Tue, Apr 26, 2022 at 04:06:08PM +0000, Andrea Bolognani wrote:
> > Ideas for follow-up work:
> >
> >   * improve the generator so that multi-line comments attached to
> >     enum values and macros get all newlines stripped before ending up
> >     in the XML. Right now it's done very inconsistently;
> >
> >   * include version information in the HTML documentation;
> >
> >   * whatever can be done to make apibuild.py at least somewhat sane :)
>
> Would you mind opening an issue for those and cc me there? I
> don't mind working on it later on.

Will do.

> > One more thing. Right now version tags look like
> >
> >   Since: v1.2.3
> >
> > but the "v" part doesn't really need to be there IMO, and in fact it
> > has to be stripped when generating the XML. How would you feel about
> > not having it in the documentation in the first place?
>
> IIRC, I used the 'v' because it was easier to write match
> patterns with the leading 'v' but was considering removing as
> well.  I don't mind stripping it.

Can you please prepare a patch implementing this change? There are
still a few days left before the next release is tagged.

> Another suggestion of mine, was adding other metadata tags to the
> documentation, for example, @deprecated: <version>, or info
> related to APIs that might be hypervisor specific... don't know.

The ability to mark symbols as deprecated would be very valuable I
think: for example, language bindings could decide not to expose
them. Hypervisor-specific APIs should already be relegated to the
corresponding sub-libraries (e.g. libvirt-qemu) so I don't think
that'd be applicable.

If we wanted to get real fancy, we could implement annotations
similar to the ones gtk-doc support[1], to mark things such as
whether the return value of a function is supposed to be freed by the
caller. But I have to wonder if, in the long run, it wouldn't make
more sense to evaluate switching from our homegrown API documentation
scaffolding to an off the shelf solution such as Doxygen.


[1] https://wiki.gnome.org/Projects/GObjectIntrospection/Annotations
-- 
Andrea Bolognani / Red Hat / Virtualization