Move and improve qdev API doc comments
Get series with b4
b4 am [email protected]Versions newest first
- v1 Latest3 patches 1 replyIn review
Patches in v1 No applies recorded yet
| # | Subject and files | Size | Replies | Applied |
|---|---|---|---|---|
| 1/3 | qdev: Move doc comments from qdev.c to qdev-core.hhw/ include/ include/ | +70 | 0 replies | |
| 2/3 | qdev: Document qdev_unrealize()include/ | +19 | 0 replies | |
| 3/3 | qdev: Document GPIO related functionsinclude/ | +189 | 0 replies |
Reviews trailers per patch
None of the 3 patches has a Reviewed-by or Acked-by of their own; the series has one for all of them.
| Patch | Richard Henderson |
|---|---|
| Series | R-b |
| 1/3 | |
| 2/3 | |
| 3/3 |
Trailers given in replies are filled; those carried in the patches from earlier versions are outlined with dashes.
Cover letter [PATCH for-5.1 0/3] Move and improve qdev API doc comments
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(-)
Signature · 1 line
2.20.1