[PATCH for-5.1 0/3] Move and improve qdev API doc comments

[Peter Maydell <peter.maydell@linaro.org>]

This patchset adds documentation comments to qdev-core.h (and in a few
cases qdev-properties.h) to functions (but not all functions!) which
were missing them.

The prompt for this was Markus' recent welcome cleanup and correction
of the qdev realize functions to get reference count and bus parenting
handling right. Markus put doc comments for new/changed functions in
the qdev.c file. This is something where I have a fairly strong opinion:
 * the right place for doc comments for functions which expose API
   to the rest of QEMU is in the header file, not the .c file
 * we should be consistent about this, especially within a single
   header file but more generally as a project

So patch 1 moves doc comments from qdev.c to qdev-core.h (or
for a few functions qdev-properties.h) to join the doc comments
that were already in those header files. I have expanded on the
comments in some places where I thought that summaries of the
intended use case for the API was helpful.

Because I didn't want to send out a patch that was moving doc
comments around to fit my asserted preferred style and nothing else,
I have attempted to sweeten the pot a bit with patches 2 and 3, which
provide new doc comments for previously undocumented functions:
qdev_unrealize(), and also all the GPIO creation/connection APIs.

thanks
-- PMM

Peter Maydell (3):
  qdev: Move doc comments from qdev.c to qdev-core.h
  qdev: Document qdev_unrealize()
  qdev: Document GPIO related functions

 include/hw/qdev-core.h       | 267 ++++++++++++++++++++++++++++++++++-
 include/hw/qdev-properties.h |  13 ++
 hw/core/qdev.c               |  33 -----
 3 files changed, 278 insertions(+), 35 deletions(-)

-- 
2.20.1