[Qemu-devel] [PATCH RFC v5 16/32] qapi: Generate comments to simplify splitting for review

[Markus Armbruster]

The effect of the previous few patches on generated files is hard to
review, because stuff gets generated in different order, which renders
diffs of the generated files useless.

To get reviewable diffs, we need to split the generated files into
suitable parts: put every top-level declaration in a file named like
the thing declared, so we can diff top-level declarations regardless
of their order in the generated files.

Since I don't feel like parsing C, simply generate a // comment
identifying the declaration right before each top-level declaration.
This lets us split with a simple shell loop:

    mkdir -p n
    for i in q*-{commands,marshal,event,types,visit}.[ch]
    do
        csplit -n 4 -s "$i" '/^\/\//' '{*}'
        for j in xx*
        do
            read h t <$j
            [ "$h" = "//" ] || t=""
            mv $j n/"$i-${j#xx}-${t/ /-}"
        done
    done

Splits each file F into F-NUMB-ID, where NUMB counts up from 0001, and
ID comes from the // comment.

To check the split's sane, we can run

    for i in q*-{commands,marshal,event,types,visit}.[ch]
    do cat n/$i-* | diff $i -
    done

We got a commit similar to this one right before the patches we want
to check.  If you have that commit's split files in directory o, and
this commit's split files in directory n, you can diff them with this
loop:

    for i in `(ls o; ls n) | sed -n 's/-[0-9][0-9][0-9][0-9]-/-*-/p' | sort | 
uniq`
    do
        diff -uBp o/$i n/$i
    done

Complete annotated output:

* QAPIEvent_lookup[] and enum QAPIEvent

  Innocent changes due to "De-duplicate enum code generation".

    --- o/qapi-event.c-0037-def-QAPIEvent_lookup        2015-08-04 
12:47:16.479980075 +0200
    +++ n/qapi-event.c-0037-def-QAPIEvent_lookup        2015-08-04 
13:02:46.336626925 +0200
    @@ -1,39 +1,39 @@
     // def QAPIEvent_lookup
    -const char *QAPIEvent_lookup[] = {
    -    "BLOCK_IMAGE_CORRUPTED",
    -    "BLOCK_IO_ERROR",
    -    "BLOCK_JOB_COMPLETED",
    -    "BLOCK_JOB_CANCELLED",
    -    "BLOCK_JOB_ERROR",
    -    "BLOCK_JOB_READY",
    -    "BLOCK_WRITE_THRESHOLD",
    -    "DEVICE_TRAY_MOVED",
    -    "SHUTDOWN",
    -    "POWERDOWN",
    -    "RESET",
    -    "STOP",
    -    "RESUME",
    -    "SUSPEND",
    -    "SUSPEND_DISK",
    -    "WAKEUP",
    -    "RTC_CHANGE",
    -    "WATCHDOG",
    -    "DEVICE_DELETED",
    -    "NIC_RX_FILTER_CHANGED",
    -    "VNC_CONNECTED",
    -    "VNC_INITIALIZED",
    -    "VNC_DISCONNECTED",
    -    "SPICE_CONNECTED",
    -    "SPICE_INITIALIZED",
    -    "SPICE_DISCONNECTED",
    -    "SPICE_MIGRATE_COMPLETED",
    -    "MIGRATION",
    -    "ACPI_DEVICE_OST",
    -    "BALLOON_CHANGE",
    -    "GUEST_PANICKED",
    -    "QUORUM_FAILURE",
    -    "QUORUM_REPORT_BAD",
    -    "VSERPORT_CHANGE",
    -    "MEM_UNPLUG_ERROR",
    -    NULL,
    +const char *const QAPIEvent_lookup[] = {
    +    [QAPI_EVENT_ACPI_DEVICE_OST] = "ACPI_DEVICE_OST",
    +    [QAPI_EVENT_BALLOON_CHANGE] = "BALLOON_CHANGE",
    +    [QAPI_EVENT_BLOCK_IMAGE_CORRUPTED] = "BLOCK_IMAGE_CORRUPTED",
    +    [QAPI_EVENT_BLOCK_IO_ERROR] = "BLOCK_IO_ERROR",
    +    [QAPI_EVENT_BLOCK_JOB_CANCELLED] = "BLOCK_JOB_CANCELLED",
    +    [QAPI_EVENT_BLOCK_JOB_COMPLETED] = "BLOCK_JOB_COMPLETED",
    +    [QAPI_EVENT_BLOCK_JOB_ERROR] = "BLOCK_JOB_ERROR",
    +    [QAPI_EVENT_BLOCK_JOB_READY] = "BLOCK_JOB_READY",
    +    [QAPI_EVENT_BLOCK_WRITE_THRESHOLD] = "BLOCK_WRITE_THRESHOLD",
    +    [QAPI_EVENT_DEVICE_DELETED] = "DEVICE_DELETED",
    +    [QAPI_EVENT_DEVICE_TRAY_MOVED] = "DEVICE_TRAY_MOVED",
    +    [QAPI_EVENT_GUEST_PANICKED] = "GUEST_PANICKED",
    +    [QAPI_EVENT_MEM_UNPLUG_ERROR] = "MEM_UNPLUG_ERROR",
    +    [QAPI_EVENT_MIGRATION] = "MIGRATION",
    +    [QAPI_EVENT_NIC_RX_FILTER_CHANGED] = "NIC_RX_FILTER_CHANGED",
    +    [QAPI_EVENT_POWERDOWN] = "POWERDOWN",
    +    [QAPI_EVENT_QUORUM_FAILURE] = "QUORUM_FAILURE",
    +    [QAPI_EVENT_QUORUM_REPORT_BAD] = "QUORUM_REPORT_BAD",
    +    [QAPI_EVENT_RESET] = "RESET",
    +    [QAPI_EVENT_RESUME] = "RESUME",
    +    [QAPI_EVENT_RTC_CHANGE] = "RTC_CHANGE",
    +    [QAPI_EVENT_SHUTDOWN] = "SHUTDOWN",
    +    [QAPI_EVENT_SPICE_CONNECTED] = "SPICE_CONNECTED",
    +    [QAPI_EVENT_SPICE_DISCONNECTED] = "SPICE_DISCONNECTED",
    +    [QAPI_EVENT_SPICE_INITIALIZED] = "SPICE_INITIALIZED",
    +    [QAPI_EVENT_SPICE_MIGRATE_COMPLETED] = "SPICE_MIGRATE_COMPLETED",
    +    [QAPI_EVENT_STOP] = "STOP",
    +    [QAPI_EVENT_SUSPEND] = "SUSPEND",
    +    [QAPI_EVENT_SUSPEND_DISK] = "SUSPEND_DISK",
    +    [QAPI_EVENT_VNC_CONNECTED] = "VNC_CONNECTED",
    +    [QAPI_EVENT_VNC_DISCONNECTED] = "VNC_DISCONNECTED",
    +    [QAPI_EVENT_VNC_INITIALIZED] = "VNC_INITIALIZED",
    +    [QAPI_EVENT_VSERPORT_CHANGE] = "VSERPORT_CHANGE",
    +    [QAPI_EVENT_WAKEUP] = "WAKEUP",
    +    [QAPI_EVENT_WATCHDOG] = "WATCHDOG",
    +    [QAPI_EVENT_MAX] = NULL,
     };
    --- o/qapi-event.h-0037-decl-QAPIEvent_lookup       2015-08-04 
12:47:16.480980103 +0200
    +++ n/qapi-event.h-0038-decl-QAPIEvent_lookup       2015-08-04 
13:02:46.387628338 +0200
    @@ -1,2 +1,3 @@
     // decl QAPIEvent_lookup
    -extern const char *QAPIEvent_lookup[];
    +extern const char *const QAPIEvent_lookup[];
    +
    --- o/qapi-event.h-0038-typedef-QAPIEvent   2015-08-04 12:47:16.480980103 
+0200
    +++ n/qapi-event.h-0037-typedef-QAPIEvent   2015-08-04 13:02:46.387628338 
+0200
    @@ -1,40 +1,40 @@
     // typedef QAPIEvent
     typedef enum QAPIEvent {
    -    QAPI_EVENT_BLOCK_IMAGE_CORRUPTED = 0,
    -    QAPI_EVENT_BLOCK_IO_ERROR = 1,
    -    QAPI_EVENT_BLOCK_JOB_COMPLETED = 2,
    -    QAPI_EVENT_BLOCK_JOB_CANCELLED = 3,
    -    QAPI_EVENT_BLOCK_JOB_ERROR = 4,
    -    QAPI_EVENT_BLOCK_JOB_READY = 5,
    -    QAPI_EVENT_BLOCK_WRITE_THRESHOLD = 6,
    -    QAPI_EVENT_DEVICE_TRAY_MOVED = 7,
    -    QAPI_EVENT_SHUTDOWN = 8,
    -    QAPI_EVENT_POWERDOWN = 9,
    -    QAPI_EVENT_RESET = 10,
    -    QAPI_EVENT_STOP = 11,
    -    QAPI_EVENT_RESUME = 12,
    -    QAPI_EVENT_SUSPEND = 13,
    -    QAPI_EVENT_SUSPEND_DISK = 14,
    -    QAPI_EVENT_WAKEUP = 15,
    -    QAPI_EVENT_RTC_CHANGE = 16,
    -    QAPI_EVENT_WATCHDOG = 17,
    -    QAPI_EVENT_DEVICE_DELETED = 18,
    -    QAPI_EVENT_NIC_RX_FILTER_CHANGED = 19,
    -    QAPI_EVENT_VNC_CONNECTED = 20,
    -    QAPI_EVENT_VNC_INITIALIZED = 21,
    -    QAPI_EVENT_VNC_DISCONNECTED = 22,
    -    QAPI_EVENT_SPICE_CONNECTED = 23,
    +    QAPI_EVENT_ACPI_DEVICE_OST = 0,
    +    QAPI_EVENT_BALLOON_CHANGE = 1,
    +    QAPI_EVENT_BLOCK_IMAGE_CORRUPTED = 2,
    +    QAPI_EVENT_BLOCK_IO_ERROR = 3,
    +    QAPI_EVENT_BLOCK_JOB_CANCELLED = 4,
    +    QAPI_EVENT_BLOCK_JOB_COMPLETED = 5,
    +    QAPI_EVENT_BLOCK_JOB_ERROR = 6,
    +    QAPI_EVENT_BLOCK_JOB_READY = 7,
    +    QAPI_EVENT_BLOCK_WRITE_THRESHOLD = 8,
    +    QAPI_EVENT_DEVICE_DELETED = 9,
    +    QAPI_EVENT_DEVICE_TRAY_MOVED = 10,
    +    QAPI_EVENT_GUEST_PANICKED = 11,
    +    QAPI_EVENT_MEM_UNPLUG_ERROR = 12,
    +    QAPI_EVENT_MIGRATION = 13,
    +    QAPI_EVENT_NIC_RX_FILTER_CHANGED = 14,
    +    QAPI_EVENT_POWERDOWN = 15,
    +    QAPI_EVENT_QUORUM_FAILURE = 16,
    +    QAPI_EVENT_QUORUM_REPORT_BAD = 17,
    +    QAPI_EVENT_RESET = 18,
    +    QAPI_EVENT_RESUME = 19,
    +    QAPI_EVENT_RTC_CHANGE = 20,
    +    QAPI_EVENT_SHUTDOWN = 21,
    +    QAPI_EVENT_SPICE_CONNECTED = 22,
    +    QAPI_EVENT_SPICE_DISCONNECTED = 23,
         QAPI_EVENT_SPICE_INITIALIZED = 24,
    -    QAPI_EVENT_SPICE_DISCONNECTED = 25,
    -    QAPI_EVENT_SPICE_MIGRATE_COMPLETED = 26,
    -    QAPI_EVENT_MIGRATION = 27,
    -    QAPI_EVENT_ACPI_DEVICE_OST = 28,
    -    QAPI_EVENT_BALLOON_CHANGE = 29,
    -    QAPI_EVENT_GUEST_PANICKED = 30,
    -    QAPI_EVENT_QUORUM_FAILURE = 31,
    -    QAPI_EVENT_QUORUM_REPORT_BAD = 32,
    -    QAPI_EVENT_VSERPORT_CHANGE = 33,
    -    QAPI_EVENT_MEM_UNPLUG_ERROR = 34,
    +    QAPI_EVENT_SPICE_MIGRATE_COMPLETED = 25,
    +    QAPI_EVENT_STOP = 26,
    +    QAPI_EVENT_SUSPEND = 27,
    +    QAPI_EVENT_SUSPEND_DISK = 28,
    +    QAPI_EVENT_VNC_CONNECTED = 29,
    +    QAPI_EVENT_VNC_DISCONNECTED = 30,
    +    QAPI_EVENT_VNC_INITIALIZED = 31,
    +    QAPI_EVENT_VSERPORT_CHANGE = 32,
    +    QAPI_EVENT_WAKEUP = 33,
    +    QAPI_EVENT_WATCHDOG = 34,
         QAPI_EVENT_MAX = 35,
     } QAPIEvent;

* Guards QAPI_TYPES_BUILTIN_STRUCT_DECL and
  QAPI_TYPES_BUILTIN_CLEANUP_DECL replaced by just QAPI_TYPES_BUILTIN

    diff: o/qapi-types.h-*-guardend-QAPI_TYPES_BUILTIN: No such file or 
directory
    diff: n/qapi-types.h-*-guardend-QAPI_TYPES_BUILTIN_CLEANUP_DECL: No such 
file or directory
    diff: n/qapi-types.h-*-guardend-QAPI_TYPES_BUILTIN_STRUCT_DECL: No such 
file or directory
    diff: o/qapi-types.h-*-guardstart-QAPI_TYPES_BUILTIN: No such file or 
directory
    diff: n/qapi-types.h-*-guardstart-QAPI_TYPES_BUILTIN_CLEANUP_DECL: No such 
file or directory
    diff: n/qapi-types.h-*-guardstart-QAPI_TYPES_BUILTIN_STRUCT_DECL: No such 
file or directory

* A bunch of new forward declarations due to different ordering

    diff: o/qapi-visit.c-*-decl-visit_type_BlockdevOptionsArchipelago_fields: 
No such file or directory
    diff: o/qapi-visit.c-*-decl-visit_type_BlockdevOptionsBlkdebug_fields: No 
such file or directory
    diff: o/qapi-visit.c-*-decl-visit_type_BlockdevOptionsBlkverify_fields: No 
such file or directory
    diff: o/qapi-visit.c-*-decl-visit_type_BlockdevOptionsFile_fields: No such 
file or directory
    diff: 
o/qapi-visit.c-*-decl-visit_type_BlockdevOptionsGenericCOWFormat_fields: No 
such file or directory
    diff: o/qapi-visit.c-*-decl-visit_type_BlockdevOptionsGenericFormat_fields: 
No such file or directory
    diff: o/qapi-visit.c-*-decl-visit_type_BlockdevOptionsNull_fields: No such 
file or directory
    diff: o/qapi-visit.c-*-decl-visit_type_BlockdevOptionsQcow2_fields: No such 
file or directory
    diff: o/qapi-visit.c-*-decl-visit_type_BlockdevOptionsQuorum_fields: No 
such file or directory
    diff: o/qapi-visit.c-*-decl-visit_type_BlockdevOptionsVVFAT_fields: No such 
file or directory

* New visitors due to "qapi-visit: Convert to QAPISchemaVisitor, fixing bugs"

    diff: o/qapi-visit.c-*-def-visit_type_BlockdevRefKind: No such file or 
directory
    diff: o/qapi-visit.c-*-def-visit_type_Qcow2OverlapChecksKind: No such file 
or directory

* Guard QAPI_VISIT_BUILTIN_VISITOR_DECL replaced by QAPI_VISIT_BUILTIN

    diff: o/qapi-visit.h-*-guardend-QAPI_VISIT_BUILTIN: No such file or 
directory
    diff: n/qapi-visit.h-*-guardend-QAPI_VISIT_BUILTIN_VISITOR_DECL: No such 
file or directory
    diff: o/qapi-visit.h-*-guardstart-QAPI_VISIT_BUILTIN: No such file or 
directory
    diff: n/qapi-visit.h-*-guardstart-QAPI_VISIT_BUILTIN_VISITOR_DECL: No such 
file or directory

Signed-off-by: Markus Armbruster <address@hidden>
---
 scripts/qapi-commands.py | 7 +++++++
 scripts/qapi-event.py    | 9 +++++++++
 scripts/qapi-types.py    | 8 ++++++++
 scripts/qapi-visit.py    | 9 +++++++++
 scripts/qapi.py          | 8 ++++++++
 5 files changed, 41 insertions(+)

diff --git a/scripts/qapi-commands.py b/scripts/qapi-commands.py
index a68517a..72b34d3 100644
--- a/scripts/qapi-commands.py
+++ b/scripts/qapi-commands.py
@@ -24,6 +24,7 @@ def generate_command_decl(name, args, ret_type):
                 arglist += "bool has_%s, " % c_name(memb.name)
             arglist += "%s %s, " % (argtype, c_name(memb.name))
     return mcgen('''
+// decl qmp_%(name)s
 %(ret_type)s qmp_%(name)s(%(args)sError **errp);
 ''',
                  ret_type=(ret_type and ret_type.c_type()) or 'void',
@@ -168,6 +169,7 @@ def gen_marshal_output(name, ret_type):
 
     ret = mcgen('''
 
+// def qmp_marshal_output_%(c_name)s
 static void qmp_marshal_output_%(c_name)s(%(c_ret_type)s ret_in, QObject 
**ret_out, Error **errp)
 {
     Error *local_err = NULL;
@@ -207,10 +209,12 @@ def gen_marshal_input(name, args, ret_type, middle_mode):
 
     ret = mcgen('''
 
+// def qmp_marshal_input_%(name)s
 %(header)s
 {
     Error *local_err = NULL;
 ''',
+                name=name,
                 header=hdr)
 
     if ret_type:
@@ -263,6 +267,7 @@ qmp_register_command("%(name)s", 
qmp_marshal_input_%(c_name)s, %(opts)s);
 def gen_registry(registry):
     ret = mcgen('''
 
+// def qmp_init_marshal
 static void qmp_init_marshal(void)
 {
 ''')
@@ -270,6 +275,7 @@ static void qmp_init_marshal(void)
     ret += mcgen('''
 }
 
+// decl qapi_init
 qapi_init(qmp_init_marshal);
 ''')
     return ret
@@ -299,6 +305,7 @@ class QAPISchemaGenCommandVisitor(QAPISchemaVisitor):
         if ret_type:
             self.defn += gen_marshal_output(name, ret_type)
         if middle_mode:
+            self.decl += '// decl gen_marshal_input_%s\n' % name
             self.decl += gen_marshal_input_decl(name, middle_mode) + ';\n'
         self.defn += gen_marshal_input(name, arg_type, ret_type, middle_mode)
         if not middle_mode:
diff --git a/scripts/qapi-event.py b/scripts/qapi-event.py
index d19acda..199a779 100644
--- a/scripts/qapi-event.py
+++ b/scripts/qapi-event.py
@@ -11,6 +11,7 @@
 # This work is licensed under the terms of the GNU GPL, version 2.
 # See the COPYING file in the top-level directory.
 
+import re;
 from qapi import *
 
 def _generate_event_api_name(event_name, params):
@@ -34,22 +35,30 @@ def _generate_event_api_name(event_name, params):
 # Following are the core functions that generate C APIs to emit event.
 
 def generate_event_declaration(api_name):
+    match = re.match(r'void ([A-Za-z0-9_]+)', api_name)
+    name = match.group(1)
     return mcgen('''
 
+// decl %(name)s
 %(api_name)s;
 ''',
+                 name=name,
                  api_name = api_name)
 
 def generate_event_implement(api_name, event_name, params):
+    match = re.match(r'void ([A-Za-z0-9_]+)', api_name)
+    name = match.group(1)
     # step 1: declare any variables
     ret = mcgen("""
 
+// def %(name)s
 %(api_name)s
 {
     QDict *qmp;
     Error *local_err = NULL;
     QMPEventFuncEmit emit;
 """,
+                name=name,
                 api_name = api_name)
 
     if params and params.members:
diff --git a/scripts/qapi-types.py b/scripts/qapi-types.py
index bc20136..26c045a 100644
--- a/scripts/qapi-types.py
+++ b/scripts/qapi-types.py
@@ -16,6 +16,7 @@ from qapi import *
 def gen_fwd_object_or_array(name):
     return mcgen('''
 
+// typedef %(name)s
 typedef struct %(name)s %(name)s;
 ''',
                  name=c_name(name))
@@ -23,6 +24,7 @@ typedef struct %(name)s %(name)s;
 def gen_array(name, element_type):
     return mcgen('''
 
+// struct %(name)s
 struct %(name)s {
     union {
         %(c_type)s value;
@@ -57,6 +59,7 @@ def generate_struct_fields(members):
 def gen_struct(name, base, members):
     ret = mcgen('''
 
+// struct %(name)s
 struct %(name)s {
 ''',
                 name=c_name(name))
@@ -83,6 +86,7 @@ struct %(name)s {
 def gen_alternate_qtypes_decl(name):
     return mcgen('''
 
+// decl %(c_name)s_qtypes
 extern const int %(c_name)s_qtypes[];
 ''',
                  c_name=c_name(name))
@@ -90,6 +94,7 @@ extern const int %(c_name)s_qtypes[];
 def gen_alternate_qtypes(name, variants):
     ret = mcgen('''
 
+// def %(name)s_qtypes
 const int %(name)s_qtypes[QTYPE_MAX] = {
 ''',
                 name=c_name(name))
@@ -115,6 +120,7 @@ def gen_union(name, base, variants):
 
     ret = mcgen('''
 
+// struct %(name)s
 struct %(name)s {
 ''',
                 name=name)
@@ -169,6 +175,7 @@ struct %(name)s {
 def generate_type_cleanup_decl(name):
     ret = mcgen('''
 
+// decl qapi_free_%(name)s
 void qapi_free_%(name)s(%(name)s *obj);
 ''',
                 name=c_name(name))
@@ -177,6 +184,7 @@ void qapi_free_%(name)s(%(name)s *obj);
 def generate_type_cleanup(name):
     ret = mcgen('''
 
+// def qapi_free_%(name)s
 void qapi_free_%(name)s(%(name)s *obj)
 {
     QapiDeallocVisitor *md;
diff --git a/scripts/qapi-visit.py b/scripts/qapi-visit.py
index cfebcb7..bec1664 100644
--- a/scripts/qapi-visit.py
+++ b/scripts/qapi-visit.py
@@ -27,12 +27,14 @@ def generate_visit_implicit_struct(type):
         # Need a forward declaration
         ret += mcgen('''
 
+// decl visit_type_%(c_type)s_fields
 static void visit_type_%(c_type)s_fields(Visitor *m, %(c_type)s **obj, Error 
**errp);
 ''',
                      c_type=type.c_name())
 
     ret += mcgen('''
 
+// def visit_type_implicit_%(c_type)s
 static void visit_type_implicit_%(c_type)s(Visitor *m, %(c_type)s **obj, Error 
**errp)
 {
     Error *err = NULL;
@@ -58,6 +60,7 @@ def generate_visit_struct_fields(name, members, base = None):
 
     ret += mcgen('''
 
+// def visit_type_%(name)s_fields
 static void visit_type_%(name)s_fields(Visitor *m, %(name)s **obj, Error 
**errp)
 {
     Error *err = NULL;
@@ -140,6 +143,7 @@ def gen_visit_struct(name, base, members):
 
     ret += mcgen('''
 
+// def visit_type_%(name)s
 void visit_type_%(name)s(Visitor *m, %(name)s **obj, const char *name, Error 
**errp)
 {
 ''',
@@ -155,6 +159,7 @@ void visit_type_%(name)s(Visitor *m, %(name)s **obj, const 
char *name, Error **e
 def gen_visit_list(name, element_type):
     return mcgen('''
 
+// def visit_type_%(name)s
 void visit_type_%(name)s(Visitor *m, %(name)s **obj, const char *name, Error 
**errp)
 {
     Error *err = NULL;
@@ -185,6 +190,7 @@ out:
 def generate_visit_enum(name):
     return mcgen('''
 
+// def visit_type_%(c_name)s
 void visit_type_%(c_name)s(Visitor *m, %(c_name)s *obj, const char *name, 
Error **errp)
 {
     visit_type_enum(m, (int *)obj, %(c_name)s_lookup, "%(name)s", name, errp);
@@ -195,6 +201,7 @@ void visit_type_%(c_name)s(Visitor *m, %(c_name)s *obj, 
const char *name, Error
 def gen_visit_alternate(name, variants):
     ret = mcgen('''
 
+// def visit_type_%(name)s
 void visit_type_%(name)s(Visitor *m, %(name)s **obj, const char *name, Error 
**errp)
 {
     Error *err = NULL;
@@ -252,6 +259,7 @@ def gen_visit_union(name, base, variants):
 
     ret += mcgen('''
 
+// def visit_type_%(c_name)s
 void visit_type_%(c_name)s(Visitor *m, %(c_name)s **obj, const char *name, 
Error **errp)
 {
     Error *err = NULL;
@@ -336,6 +344,7 @@ def gen_visit_decl(name, scalar=False):
     if not scalar:
         c_type += '*'
     return mcgen('''
+// decl visit_type_%(c_name)s
 void visit_type_%(c_name)s(Visitor *m, %(c_type)sobj, const char *name, Error 
**errp);
 ''',
                  c_name=c_name(name), c_type=c_type)
diff --git a/scripts/qapi.py b/scripts/qapi.py
index e1268f4..debeade 100644
--- a/scripts/qapi.py
+++ b/scripts/qapi.py
@@ -1471,6 +1471,7 @@ def guardname(filename):
 def guardstart(name):
     return mcgen('''
 
+// guardstart %(name)s
 #ifndef %(name)s
 #define %(name)s
 
@@ -1480,6 +1481,7 @@ def guardstart(name):
 def guardend(name):
     return mcgen('''
 
+// guardend %(name)s
 #endif /* %(name)s */
 
 ''',
@@ -1488,6 +1490,7 @@ def guardend(name):
 def generate_enum_lookup(name, values):
     ret = mcgen('''
 
+// def %(name)s_lookup
 const char *const %(name)s_lookup[] = {
 ''',
                 name=c_name(name))
@@ -1510,12 +1513,14 @@ def generate_enum(name, values):
     name = c_name(name)
     lookup_decl = mcgen('''
 
+// decl %(name)s_lookup
 extern const char *const %(name)s_lookup[];
 ''',
                 name=name)
 
     enum_decl = mcgen('''
 
+// typedef %(name)s
 typedef enum %(name)s {
 ''',
                 name=name)
@@ -1619,12 +1624,14 @@ def open_output(output_dir, do_c, do_h, prefix, c_file, 
h_file,
     fdecl = maybe_open(do_h, h_file, 'w')
 
     fdef.write(mcgen('''
+// prologue
 /* AUTOMATICALLY GENERATED, DO NOT MODIFY */
 %(comment)s
 ''',
                      comment = c_comment))
 
     fdecl.write(mcgen('''
+// prologue
 /* AUTOMATICALLY GENERATED, DO NOT MODIFY */
 %(comment)s
 #ifndef %(guard)s
@@ -1637,6 +1644,7 @@ def open_output(output_dir, do_c, do_h, prefix, c_file, 
h_file,
 
 def close_output(fdef, fdecl):
     fdecl.write('''
+// epilogue
 #endif
 ''')
     fdecl.close()
-- 
2.4.3