Re: [Qemu-devel] [PATCH 1/2] qapi: Add comments to aid debugging generated introspection

[Eric Blake]

On 06/29/2018 02:55 PM, Eric Blake wrote:
> We consciously chose in commit 1a9a507b to hide QAPI type names
> from the generated introspection output, but added a command line
> option -u to unmask the type name when doing a debug build.  At
> that time, we generated a monolithic C string, so there was no
> better way to do things (we could not really inject comments).
>
> Later, in commit 7d0f982b, we switched the generation to output
> a QLit object, in part to make it easier for future addition of
> conditional compilation.  But this switch has also made it easier
> to interject strategic comments.  That commit also forgot to
> delete some now-stale comments about long generated line lengths.
>
> For now, type name debug aid comments are only output once per
> meta-type, rather than at all uses of the number used to encode
> the type to the introspection data.  But this is still a lot
> more convenient than having to regenerate the file with the
> unmask operation temporarily turned on.
...

> Signed-off-by: Eric Blake <address@hidden>
> ---
>   scripts/qapi/introspect.py | 11 ++++++++---
>   1 file changed, 8 insertions(+), 3 deletions(-)

Misses a change to docs/devel/qapi-code.gen.tx:

diff --git i/docs/devel/qapi-code-gen.txt w/docs/devel/qapi-code-gen.txt
index 88a70e4d451..0c98c7d7b6c 100644
--- i/docs/devel/qapi-code-gen.txt
+++ w/docs/devel/qapi-code-gen.txt
@@ -1392,6 +1392,7 @@ Example:
             { }
         })),
         QLIT_QDICT(((QLitDictEntry[]) {
+            /* q_empty */
             { "members", QLIT_QLIST(((QLitObject[]) {
                 { }
             })) },

> @@ -118,8 +121,8 @@ const QLitObject %(c_name)s = %(c_string)s;
>           if typ not in self._used_types:
>               self._used_types.append(typ)
>           # Clients should examine commands and events, not types.  Hide
> -        # type names to reduce the temptation.  Also saves a few
> -        # characters.
> +        # type names as integers to reduce the temptation, but provide
> +        # comments for debugging aid.

When I wrote the patch, I assumed the final sentence of the comment was 
talking about fewer characters in the generated .c file (I nuked it, 
since adding comments makes for a longer, not shorter, generated .c 
file); but now that I'm writing this email, I see it could also refer to 
fewer characters sent over the wire in the QMP command (which length is 
unchanged by this patch, but was a 13KiB savings compared to the 
unmasked version, per commit 1a9a507b).  So feel free to bikeshed this 
comment.

--
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org