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
