Skip to content

Move and improve qdev API doc comments

Peter Maydell qemu-devel 1 version In review

Get series with b4
b4 am [email protected]

Versions newest first

  1. v1 Latest3 patches 1 replyIn review

Patches in v1 No applies recorded yet

#Subject and filesSizeRepliesApplied
1/3qdev: Move doc comments from qdev.c to qdev-core.hhw/core/qdev.c include/hw/qdev-core.h include/hw/qdev-properties.h+70 -330 replies
2/3qdev: Document qdev_unrealize()include/hw/qdev-core.h+19 -00 replies
3/3qdev: Document GPIO related functionsinclude/hw/qdev-core.h+189 -20 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.

PatchRichard Henderson
SeriesR-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.

Read the v1 thread

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