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