diff mbox

[v8,07/21] qapi: avoid interleaving sections and parameters

Message ID 20170113144135.5150-8-marcandre.lureau@redhat.com
State New
Headers show

Commit Message

Marc-André Lureau Jan. 13, 2017, 2:41 p.m. UTC 
Follow documentation guideline, body, parameters then additional
sections.

Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
---
 qapi-schema.json     | 10 +++++-----
 qapi/event.json      |  4 ++--
 qapi/introspect.json |  3 +--
 3 files changed, 8 insertions(+), 9 deletions(-)

Comments

Markus Armbruster Jan. 13, 2017, 4:14 p.m. UTC | #1 
Marc-André Lureau <marcandre.lureau@redhat.com> writes:

> Follow documentation guideline, body, parameters then additional
> sections.
>
> Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>

As proposed in review of v7, I'm replacing commit message by

  qapi: Reorder doc comments for future doc generator
  
  The doc generator we're going to add expects a fairly rigid doc
  comment structure.  Reorder / rephrase some doc comments to please it.

if that's okay with you.
diff mbox

Patch

diff --git a/qapi-schema.json b/qapi-schema.json
index 6c251605ac..c1af70057d 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -4733,17 +4733,17 @@ 
 # it should be passed by management with device_add command when
 # a CPU is being hotplugged.
 #
+# @node-id: #optional NUMA node ID the CPU belongs to
+# @socket-id: #optional socket number within node/board the CPU belongs to
+# @core-id: #optional core number within socket the CPU belongs to
+# @thread-id: #optional thread number within core the CPU belongs to
+#
 # Note: currently there are 4 properties that could be present
 # but management should be prepared to pass through other
 # properties with device_add command to allow for future
 # interface extension. This also requires the filed names to be kept in
 # sync with the properties passed to -device/device_add.
 #
-# @node-id: #optional NUMA node ID the CPU belongs to
-# @socket-id: #optional socket number within node/board the CPU belongs to
-# @core-id: #optional core number within socket the CPU belongs to
-# @thread-id: #optional thread number within core the CPU belongs to
-#
 # Since: 2.7
 ##
 { 'struct': 'CpuInstanceProperties',
diff --git a/qapi/event.json b/qapi/event.json
index 37bf34ed6d..c7689b211d 100644
--- a/qapi/event.json
+++ b/qapi/event.json
@@ -272,9 +272,9 @@ 
 #
 # Emitted when guest executes ACPI _OST method.
 #
-# Since: 2.1
-#
 # @info: ACPIOSTInfo type as described in qapi-schema.json
+#
+# Since: 2.1
 ##
 { 'event': 'ACPI_DEVICE_OST',
      'data': { 'info': 'ACPIOSTInfo' } }
diff --git a/qapi/introspect.json b/qapi/introspect.json
index 464097a235..f6adc439bb 100644
--- a/qapi/introspect.json
+++ b/qapi/introspect.json
@@ -78,14 +78,13 @@ 
 # @SchemaInfo:
 #
 # @name: the entity's name, inherited from @base.
+#        The SchemaInfo is always referenced by this name.
 #        Commands and events have the name defined in the QAPI schema.
 #        Unlike command and event names, type names are not part of
 #        the wire ABI.  Consequently, type names are meaningless
 #        strings here, although they are still guaranteed unique
 #        regardless of @meta-type.
 #
-# All references to other SchemaInfo are by name.
-#
 # @meta-type: the entity's meta type, inherited from @base.
 #
 # Additional members depend on the value of @meta-type.