Re: [PULL 00/84] QOM patches for 2020-06-15

["Philippe Mathieu-Daudé" <philmd@redhat.com>]

On 6/27/20 5:11 PM, Peter Maydell wrote:
> On Sat, 27 Jun 2020 at 12:53, Markus Armbruster <armbru@redhat.com> wrote:
>> Peter Maydell <peter.maydell@linaro.org> writes:
>>> Hi. I've just noticed that this commit added new global-scope
>>> functions to header files without documentation comments, eg
>>>
>>> bool qdev_realize_and_unref(DeviceState *dev, BusState *bus, Error **errp);
>>
>> They actually have doc comments: next to their definition, just like the
>> functions they replace.
> 
>>> Please could you provide some follow-up patches that document them?
>>> I don't think we have any hope of getting people to follow whatever
>>> the correct new way to create/configure/realize devices is if we
>>> don't document it :-(   [Concrete example: I now have no idea
>>> how this is supposed to work after this patchset.]
>>
>> Please check out my function comments, and if they leave you confused,
>> let's talk about improvements.
> 
> I will have a look at them, but we should move them (wholesale
> with other documentation comments for qdev) to the header files.
> (That we are having this discussion at all demonstrates why -- people
> don't look in the C files for API documentation of functions.)
> The headers are where the API that faces the rest of QEMU should
> be documented; comments in the C files are for people who care
> about the internals of the implementation. "New prototype in a header
> file should have a doc comment" is a standard part of my code review
> I apply to any code which I see going past. We absolutely have not
> been good about documenting our facing-the-rest-of-QEMU functions
> in the past but this is an area where I think we should be raising the bar.
> 
>> I'm content to use comment placement / formatting I dislike to make my
>> code blend in, but I'm not willing to do conversion work from a style I
>> like to style I dislike.  That's a job for someone who won't feel icky
>> afterwards :)
> 
> Fair enough. I'm happy to write some patches to consistently put
> all the qdev doc info into the headers.

As a start I can respin
https://www.mail-archive.com/qemu-devel@nongnu.org/msg593422.html if you
want.