Re: [PATCH v3 13/30] docstring: function: libvirt: Add 'Since version' metadata
Hi,
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:
> Not sure I understood what is preferable. For all functions and
> typdefs and macros, it should be:
>
> Line
> 1 /**
> 2 * type_name:
> 3 *
> 4 * Maybe some comment.
> 5 *
> 6 * Maybe something about return value.
> 7 *
> 8 * Since: v1.2.3
> 9 *
> 10 */
>
> Do you suggest to not have empty line 9 ?
Correct.
Got it.
> 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.
Cheers,
Victor
Attachments:
- signature.asc (application/pgp-signature — 833 bytes)