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
