Re: [Qemu-devel] [PATCH RFC 01/21] qapi: Streamline boilerplate comment generation
On Fri, Feb 2, 2018 at 2:03 PM, Markus Armbruster wrote:
> Every generator has separate boilerplate for .h and .c, and their
> differences are boring. All of them repeat the license note.
>
> Reduce the repetition as follows. Move common text like the license
> note to common open_output(), next to the existintg common text there.
> For each generator, replace the two separate descriptions by a single
> one.
>
> While there, emit an "automatically generated" note into generated
> documentation, too.
>
> Signed-off-by: Markus Armbruster
Looks good,
Reviewed-by: Marc-André Lureau
> ---
> scripts/qapi-commands.py| 26 +++---
> scripts/qapi-event.py | 26 +++---
> scripts/qapi-introspect.py | 21 ++---
> scripts/qapi-types.py | 26 +++---
> scripts/qapi-visit.py | 26 +++---
> scripts/qapi.py | 31 ++-
> scripts/qapi2texi.py| 3 ++-
> tests/qapi-schema/doc-good.texi | 3 ++-
> 8 files changed, 36 insertions(+), 126 deletions(-)
>
> diff --git a/scripts/qapi-commands.py b/scripts/qapi-commands.py
> index 26c56c5062..25ac52503a 100644
> --- a/scripts/qapi-commands.py
> +++ b/scripts/qapi-commands.py
> @@ -255,38 +255,18 @@ class QAPISchemaGenCommandVisitor(QAPISchemaVisitor):
>
> (input_file, output_dir, do_c, do_h, prefix, opts) = parse_command_line()
>
> -c_comment = '''
> -/*
> - * schema-defined QMP->QAPI command dispatch
> +blurb = '''
> + * Schema-defined QAPI/QMP commands
> *
> * Copyright IBM, Corp. 2011
> *
> * Authors:
> * Anthony Liguori
> - *
> - * This work is licensed under the terms of the GNU LGPL, version 2.1 or
> later.
> - * See the COPYING.LIB file in the top-level directory.
> - *
> - */
> -'''
> -h_comment = '''
> -/*
> - * schema-defined QAPI function prototypes
> - *
> - * Copyright IBM, Corp. 2011
> - *
> - * Authors:
> - * Anthony Liguori
> - *
> - * This work is licensed under the terms of the GNU LGPL, version 2.1 or
> later.
> - * See the COPYING.LIB file in the top-level directory.
> - *
> - */
> '''
>
> (fdef, fdecl) = open_output(output_dir, do_c, do_h, prefix,
> 'qmp-marshal.c', 'qmp-commands.h',
> -c_comment, h_comment)
> +blurb)
>
> fdef.write(mcgen('''
>
> diff --git a/scripts/qapi-event.py b/scripts/qapi-event.py
> index 9d7134658d..31faedc689 100644
> --- a/scripts/qapi-event.py
> +++ b/scripts/qapi-event.py
> @@ -171,38 +171,18 @@ class QAPISchemaGenEventVisitor(QAPISchemaVisitor):
>
> (input_file, output_dir, do_c, do_h, prefix, dummy) = parse_command_line()
>
> -c_comment = '''
> -/*
> - * schema-defined QAPI event functions
> +blurb = '''
> + * Schema-defined QAPI/QMP events
> *
> * Copyright (c) 2014 Wenchao Xia
> *
> * Authors:
> * Wenchao Xia
> - *
> - * This work is licensed under the terms of the GNU LGPL, version 2.1 or
> later.
> - * See the COPYING.LIB file in the top-level directory.
> - *
> - */
> -'''
> -h_comment = '''
> -/*
> - * schema-defined QAPI event functions
> - *
> - * Copyright (c) 2014 Wenchao Xia
> - *
> - * Authors:
> - * Wenchao Xia
> - *
> - * This work is licensed under the terms of the GNU LGPL, version 2.1 or
> later.
> - * See the COPYING.LIB file in the top-level directory.
> - *
> - */
> '''
>
> (fdef, fdecl) = open_output(output_dir, do_c, do_h, prefix,
> 'qapi-event.c', 'qapi-event.h',
> -c_comment, h_comment)
> +blurb)
>
> fdef.write(mcgen('''
> #include "qemu/osdep.h"
> diff --git a/scripts/qapi-introspect.py b/scripts/qapi-introspect.py
> index 032bcea491..83da2bdb94 100644
> --- a/scripts/qapi-introspect.py
> +++ b/scripts/qapi-introspect.py
> @@ -176,32 +176,15 @@ for o, a in opts:
> if o in ('-u', '--unmask-non-abi-names'):
> opt_unmask = True
>
> -c_comment = '''
> -/*
> +blurb = '''
> * QAPI/QMP schema introspection
> *
> * Copyright (C) 2015 Red Hat, Inc.
> - *
> - * This work is licensed under the terms of the GNU LGPL, version 2.1 or
> later.
> - * See the COPYING.LIB file in the top-level directory.
> - *
> - */
> -'''
> -h_comment = '''
> -/*
> - * QAPI/QMP schema introspection
> - *
> - * Copyright (C) 2015 Red Hat, Inc.
> - *
> - * This work is licensed under the terms of the GNU LGPL, version 2.1 or
> later.
> - * See the COPYING.LIB file in the top-level directory.
> - *
> - */
> '''
>
> (fdef, fdecl) = open_output(output_dir, do_c, do_h, prefix,
> 'qmp-introspect.c', 'qmp-introspect.h',
> -c_comment, h_comment)
> +blurb)
>
> fdef.write(mcgen('''
> #include "qemu/osdep.h"
> diff --git a/scripts/qapi-types.py b/scripts/qapi-types.py
> index 7e3051dbb9..86afc57f92 100644
> --- a/scripts/qapi-types
Re: [Qemu-devel] [PATCH RFC 01/21] qapi: Streamline boilerplate comment generation
Eric Blake writes:
> On 02/02/2018 07:03 AM, Markus Armbruster wrote:
>> Every generator has separate boilerplate for .h and .c, and their
>> differences are boring. All of them repeat the license note.
>>
>> Reduce the repetition as follows. Move common text like the license
>> note to common open_output(), next to the existintg common text there.
>
> s/existintg/existing/
Fixing...
>> For each generator, replace the two separate descriptions by a single
>> one.
>>
>> While there, emit an "automatically generated" note into generated
>> documentation, too.
>>
>> Signed-off-by: Markus Armbruster
>> ---
>
>> +++ b/scripts/qapi2texi.py
>> @@ -282,7 +282,8 @@ def main(argv):
>> print >>sys.stderr, ("%s: need pragma 'doc-required' "
>> "to generate documentation" % argv[0])
>> sys.exit(1)
>> -print texi_schema(schema)
>> +print '@c AUTOMATICALLY GENERATED, DO NOT MODIFY\n'
>> +print texi_schema(schema),
>
> Spurious addition of trailing comma. Otherwise,
This is Python's (rather unobvious) way to print without adding a
newline.
> Reviewed-by: Eric Blake
Thanks!
[Qemu-devel] [PATCH RFC 01/21] qapi: Streamline boilerplate comment generation
Every generator has separate boilerplate for .h and .c, and their
differences are boring. All of them repeat the license note.
Reduce the repetition as follows. Move common text like the license
note to common open_output(), next to the existintg common text there.
For each generator, replace the two separate descriptions by a single
one.
While there, emit an "automatically generated" note into generated
documentation, too.
Signed-off-by: Markus Armbruster
---
scripts/qapi-commands.py| 26 +++---
scripts/qapi-event.py | 26 +++---
scripts/qapi-introspect.py | 21 ++---
scripts/qapi-types.py | 26 +++---
scripts/qapi-visit.py | 26 +++---
scripts/qapi.py | 31 ++-
scripts/qapi2texi.py| 3 ++-
tests/qapi-schema/doc-good.texi | 3 ++-
8 files changed, 36 insertions(+), 126 deletions(-)
diff --git a/scripts/qapi-commands.py b/scripts/qapi-commands.py
index 26c56c5062..25ac52503a 100644
--- a/scripts/qapi-commands.py
+++ b/scripts/qapi-commands.py
@@ -255,38 +255,18 @@ class QAPISchemaGenCommandVisitor(QAPISchemaVisitor):
(input_file, output_dir, do_c, do_h, prefix, opts) = parse_command_line()
-c_comment = '''
-/*
- * schema-defined QMP->QAPI command dispatch
+blurb = '''
+ * Schema-defined QAPI/QMP commands
*
* Copyright IBM, Corp. 2011
*
* Authors:
* Anthony Liguori
- *
- * This work is licensed under the terms of the GNU LGPL, version 2.1 or later.
- * See the COPYING.LIB file in the top-level directory.
- *
- */
-'''
-h_comment = '''
-/*
- * schema-defined QAPI function prototypes
- *
- * Copyright IBM, Corp. 2011
- *
- * Authors:
- * Anthony Liguori
- *
- * This work is licensed under the terms of the GNU LGPL, version 2.1 or later.
- * See the COPYING.LIB file in the top-level directory.
- *
- */
'''
(fdef, fdecl) = open_output(output_dir, do_c, do_h, prefix,
'qmp-marshal.c', 'qmp-commands.h',
-c_comment, h_comment)
+blurb)
fdef.write(mcgen('''
diff --git a/scripts/qapi-event.py b/scripts/qapi-event.py
index 9d7134658d..31faedc689 100644
--- a/scripts/qapi-event.py
+++ b/scripts/qapi-event.py
@@ -171,38 +171,18 @@ class QAPISchemaGenEventVisitor(QAPISchemaVisitor):
(input_file, output_dir, do_c, do_h, prefix, dummy) = parse_command_line()
-c_comment = '''
-/*
- * schema-defined QAPI event functions
+blurb = '''
+ * Schema-defined QAPI/QMP events
*
* Copyright (c) 2014 Wenchao Xia
*
* Authors:
* Wenchao Xia
- *
- * This work is licensed under the terms of the GNU LGPL, version 2.1 or later.
- * See the COPYING.LIB file in the top-level directory.
- *
- */
-'''
-h_comment = '''
-/*
- * schema-defined QAPI event functions
- *
- * Copyright (c) 2014 Wenchao Xia
- *
- * Authors:
- * Wenchao Xia
- *
- * This work is licensed under the terms of the GNU LGPL, version 2.1 or later.
- * See the COPYING.LIB file in the top-level directory.
- *
- */
'''
(fdef, fdecl) = open_output(output_dir, do_c, do_h, prefix,
'qapi-event.c', 'qapi-event.h',
-c_comment, h_comment)
+blurb)
fdef.write(mcgen('''
#include "qemu/osdep.h"
diff --git a/scripts/qapi-introspect.py b/scripts/qapi-introspect.py
index 032bcea491..83da2bdb94 100644
--- a/scripts/qapi-introspect.py
+++ b/scripts/qapi-introspect.py
@@ -176,32 +176,15 @@ for o, a in opts:
if o in ('-u', '--unmask-non-abi-names'):
opt_unmask = True
-c_comment = '''
-/*
+blurb = '''
* QAPI/QMP schema introspection
*
* Copyright (C) 2015 Red Hat, Inc.
- *
- * This work is licensed under the terms of the GNU LGPL, version 2.1 or later.
- * See the COPYING.LIB file in the top-level directory.
- *
- */
-'''
-h_comment = '''
-/*
- * QAPI/QMP schema introspection
- *
- * Copyright (C) 2015 Red Hat, Inc.
- *
- * This work is licensed under the terms of the GNU LGPL, version 2.1 or later.
- * See the COPYING.LIB file in the top-level directory.
- *
- */
'''
(fdef, fdecl) = open_output(output_dir, do_c, do_h, prefix,
'qmp-introspect.c', 'qmp-introspect.h',
-c_comment, h_comment)
+blurb)
fdef.write(mcgen('''
#include "qemu/osdep.h"
diff --git a/scripts/qapi-types.py b/scripts/qapi-types.py
index 7e3051dbb9..86afc57f92 100644
--- a/scripts/qapi-types.py
+++ b/scripts/qapi-types.py
@@ -250,39 +250,19 @@ for o, a in opts:
if o in ('-b', '--builtins'):
do_builtins = True
-c_comment = '''
-/*
- * deallocation functions for schema-defined QAPI types
+blurb = '''
+ * Schema-defined QAPI types
*
* Copyright IBM, Corp. 2011
*
* Authors:
* Anthony Liguori
* Michael Roth
- *
- * This work is licensed under the terms of the
Re: [Qemu-devel] [PATCH RFC 01/21] qapi: Streamline boilerplate comment generation
On 02/02/2018 07:03 AM, Markus Armbruster wrote:
> Every generator has separate boilerplate for .h and .c, and their
> differences are boring. All of them repeat the license note.
>
> Reduce the repetition as follows. Move common text like the license
> note to common open_output(), next to the existintg common text there.
s/existintg/existing/
> For each generator, replace the two separate descriptions by a single
> one.
>
> While there, emit an "automatically generated" note into generated
> documentation, too.
>
> Signed-off-by: Markus Armbruster
> ---
> +++ b/scripts/qapi2texi.py
> @@ -282,7 +282,8 @@ def main(argv):
> print >>sys.stderr, ("%s: need pragma 'doc-required' "
> "to generate documentation" % argv[0])
> sys.exit(1)
> -print texi_schema(schema)
> +print '@c AUTOMATICALLY GENERATED, DO NOT MODIFY\n'
> +print texi_schema(schema),
Spurious addition of trailing comma. Otherwise,
Reviewed-by: Eric Blake
--
Eric Blake, Principal Software Engineer
Red Hat, Inc. +1-919-301-3266
Virtualization: qemu.org | libvirt.org
signature.asc
Description: OpenPGP digital signature
