Hi, On Fri, Apr 22, 2022 at 01:29:07AM -0700, Andrea Bolognani wrote: > On Thu, Apr 21, 2022 at 09:12:10PM +0200, Victor Toso wrote: > > On Thu, Apr 21, 2022 at 11:45:05AM -0700, Andrea Bolognani wrote: > > > On Thu, Apr 21, 2022 at 08:34:10PM +0200, Victor Toso wrote: > > > > For enum values, if they are multiple line comments, I try to > > > > follow the above too. Otherwise, to avoid adding lots of extra > > > > empty lines around where we only had a single line as comment > > > > before, I've only appended the Since tag. > > > > > > Yeah, that sounds sensible. I think it would be nice to use the > > > same multi-line, documentation-right-above-symbol style > > > everywhere, but it would most likely become too unwieldy in > > > practice, especially for large enums. > > > > Yeah. I'd instead suggest to move documentation to the top of > > typedef enum, in a similar fashion of what qemu/qapi schema does. > > > > https://github.com/qemu/qemu/blob/master/qapi/audio.json#L13 > > > > Documentation is kept close enough of the data type without > > polluting the surround definitions, etc. At the very least, it > > would use less empty lines... I think. > > Oh, I hadn't even considered that as a possibility but it does indeed > look promising. We'd have to see how it look in practice to actually > judge though. Maybe you can prototype that after we're done with this > series, if you feel like it? :) Sure, I can't promise it'll be soon after this series is done, but it'll be on my list. What is very important is to have a well defined structure for the docstrings as we'll need to do extra work on apibuild.py. Also, would make sense to add other kind of metadata besides the Since version? Cheers, Victor
Attachment:
signature.asc
Description: PGP signature
