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

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