Re: [PATCH v4 00/19] Add 'version' to other exported types
On Wed, May 04, 2022 at 01:23:25PM +0200, Victor Toso wrote:
On Wed, Apr 27, 2022 at 02:17:01AM -0700, Andrea Bolognani wrote:
> > > 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.
Please don't post a patch series as a reply to another patch series
next time. Just start a new thread.
> 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.
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.
Yeah, it's not an easy call to make. Someone would have to be willing
to spend some time attempting a port to a different tool, analizing
apibuild.py to try and guess how much effort it would be to refactor
it, and so on...
--
Andrea Bolognani / Red Hat / Virtualization