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
Attachment:
signature.asc
Description: PGP signature
