Re: [PATCH 19/36] qdev: Move array property creation/registration to separate functions

[Daniel P . Berrangé]

On Fri, Oct 30, 2020 at 02:10:26PM +0400, Marc-André Lureau wrote:
> On Fri, Oct 30, 2020 at 2:03 PM Marc-André Lureau <
> marcandre.lureau@gmail.com> wrote:
> 
> >
> >
> > On Fri, Oct 30, 2020 at 2:17 AM Eduardo Habkost <ehabkost@redhat.com>
> > wrote:
> >
> >> The array property registration code is hard to follow.  Move the
> >> two steps into separate functions that have clear
> >> responsibilities.
> >>
> >> Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
> >> ---
> >> Cc: Paolo Bonzini <pbonzini@redhat.com>
> >> Cc: "Daniel P. Berrangé" <berrange@redhat.com>
> >> Cc: Eduardo Habkost <ehabkost@redhat.com>
> >> Cc: qemu-devel@nongnu.org
> >> ---
> >>  hw/core/qdev-properties.c | 60 ++++++++++++++++++++++++++-------------
> >>  1 file changed, 41 insertions(+), 19 deletions(-)
> >>
> >> diff --git a/hw/core/qdev-properties.c b/hw/core/qdev-properties.c
> >> index 27c09255d7..1f06dfb5d5 100644
> >> --- a/hw/core/qdev-properties.c
> >> +++ b/hw/core/qdev-properties.c
> >> @@ -588,6 +588,32 @@ typedef struct {
> >>      ObjectPropertyRelease *release;
> >>  } ArrayElementProperty;
> >>
> >> +/**
> >> + * Create ArrayElementProperty based on array length property
> >> + * @array_len_prop (which was previously defined using
> >> DEFINE_PROP_ARRAY()).
> >> + */
> >>
> >
> > (some day we will have to clarify our API doc style, but not now ;)
> >
> >
> Actually, I didn't realize but we do use kerneldoc in sphinx nowadays.
> 
> Peter, shouldn't you have updated CODING_STYLE.rst to say explicitly that
> our C API should be documented with it?
> 
> How do we enforce or check the comment style across the code base, or
> per-files (without necessarily including it in the generated manual/doc)?

I'd say we should include it in the generated developer docs, and enforce
whatever level of error checking is availble at build times.

I'll happily update any API docs in code I'm subsys maintainer for, if we
actually generate and validate at build time.


Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|