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

[Victor Toso]

Hi,

On Wed, Apr 27, 2022 at 02:17:01AM -0700, Andrea Bolognani wrote:
> 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.

Yep. Missed that, sorry.

I've sent the patches in-reply-to this thread, in case we still
want them.

> > 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.

Or add warnings, etc.

> 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.

Ah, true.

What about config options that might enable/disable features?
(borrowing the idea from QEMU/qapi CONFIG_*)

> 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

I don't have a particular opinion between adding small
annotations to existing documentation (like @since and
@deprecated) to convert documentation and tooling to something
else. It comes down to benefits of converting, considering the
new dependencies, etc.

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/20220504/91c9e5c1/attachment.sig>