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

[Markus Armbruster]

Peter Maydell <peter.maydell@linaro.org> writes:

> On Mon, 15 Jun 2020 at 21:43, Markus Armbruster <armbru@redhat.com> wrote:
>>
>> The following changes since commit 7d3660e79830a069f1848bb4fa1cdf8f666424fb:
>>
>>   Merge remote-tracking branch 'remotes/bonzini/tags/for-upstream' into 
>> staging (2020-06-12 23:06:22 +0100)
>>
>> are available in the Git repository at:
>>
>>   git://repo.or.cz/qemu/armbru.git tags/pull-qom-2020-06-15
>>
>> for you to fetch changes up to b77b5b3dc7a4730d804090d359c57d33573cf85a:
>>
>>   MAINTAINERS: Make section QOM cover hw/core/*bus.c as well (2020-06-15 
>> 22:06:04 +0200)
>>
>> ----------------------------------------------------------------
>> QOM patches for 2020-06-15
>>
>> * Make "info qom-tree" show children sorted
>> * Fixes around device realization
>> * Rework how we plug into devices into their parent bus
>
> 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.

We've argued about whether to put them next to definitions or next to
declarations several times, and I'd prefer not to rehash all that now.

QEMU uses different styles of function comments.  I always try to make
my new function comments consistent with nearby existing ones, if any.

Sadly, not everybody does.  Qdev used to be locally consistent, but
we've let it degenerate into the current mess.  It's what happens when
major infrastructure subsystems have to go without a maintainer for
years.

> 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'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 :)