[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PULL 00/84] QOM patches for 2020-06-15
From: |
Philippe Mathieu-Daudé |
Subject: |
Re: [PULL 00/84] QOM patches for 2020-06-15 |
Date: |
Mon, 29 Jun 2020 09:25:09 +0200 |
User-agent: |
Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.5.0 |
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.
- [PULL 71/84] sysbus: Convert to sysbus_realize() etc. with Coccinelle, (continued)
- [PULL 71/84] sysbus: Convert to sysbus_realize() etc. with Coccinelle, Markus Armbruster, 2020/06/15
- [PULL 64/84] macio: Eliminate macio_init_child_obj(), Markus Armbruster, 2020/06/15
- [PULL 73/84] sysbus: Convert qdev_set_parent_bus() use with Coccinelle, part 1, Markus Armbruster, 2020/06/15
- [PULL 77/84] sysbus: sysbus_init_child_obj() is now unused, drop, Markus Armbruster, 2020/06/15
- Re: [PULL 00/84] QOM patches for 2020-06-15, Peter Maydell, 2020/06/16
- Re: [PULL 00/84] QOM patches for 2020-06-15, Peter Maydell, 2020/06/26