[PATCH] block/export: fix QAPI doc indentation style violation

[PATCH] block/export: fix QAPI doc indentation style violation

[Stefan Hajnoczi]

Since commit a69a6d4b4d4fae2e3d2506241e22a78ff1732283
("scripts/qapi/parser.py: improve doc comment indent handling") the QAPI
generator emits an error when unindented text follows "Returns:".

Fix block-export.json by moving the comment to make the QAPI generator
happy.

Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
---
Based-on: git://repo.or.cz/qemu/kevin.git block

 qapi/block-export.json | 24 ++++++++++++------------
 1 file changed, 12 insertions(+), 12 deletions(-)

diff --git a/qapi/block-export.json b/qapi/block-export.json
index 87ac5117cd..a793e34af9 100644
--- a/qapi/block-export.json
+++ b/qapi/block-export.json
@@ -39,21 +39,21 @@
 # server will present them as named exports; for example, another
 # QEMU instance could refer to them as "nbd:HOST:PORT:exportname=NAME".
 #
-# @addr: Address on which to listen.
-# @tls-creds: ID of the TLS credentials object (since 2.6).
-# @tls-authz: ID of the QAuthZ authorization object used to validate
-#             the client's x509 distinguished name. This object is
-#             is only resolved at time of use, so can be deleted and
-#             recreated on the fly while the NBD server is active.
-#             If missing, it will default to denying access (since 4.0).
-# @max-connections: The maximum number of connections to allow at the same
-#                   time, 0 for unlimited. (since 5.2; default: 0)
-#
-# Returns: error if the server is already running.
-#
 # Keep this type consistent with the NbdServerOptions type. The only intended
 # difference is using SocketAddressLegacy instead of SocketAddress.
 #
+# @addr: Address on which to listen.
+# @tls-creds: ID of the TLS credentials object (since 2.6).
+# @tls-authz: ID of the QAuthZ authorization object used to validate
+#             the client's x509 distinguished name. This object is
+#             is only resolved at time of use, so can be deleted and
+#             recreated on the fly while the NBD server is active.
+#             If missing, it will default to denying access (since 4.0).
+# @max-connections: The maximum number of connections to allow at the same
+#                   time, 0 for unlimited. (since 5.2; default: 0)
+#
+# Returns: error if the server is already running.
+#
 # Since: 1.3.0
 ##
 { 'command': 'nbd-server-start',
-- 
2.26.2

Re: [PATCH] block/export: fix QAPI doc indentation style violation

[Kevin Wolf]

Am 01.10.2020 um 15:14 hat Stefan Hajnoczi geschrieben:
> Since commit a69a6d4b4d4fae2e3d2506241e22a78ff1732283
> ("scripts/qapi/parser.py: improve doc comment indent handling") the QAPI
> generator emits an error when unindented text follows "Returns:".
> 
> Fix block-export.json by moving the comment to make the QAPI generator
> happy.
> 
> Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
> ---
> Based-on: git://repo.or.cz/qemu/kevin.git block

Sorry, this is a mismerge in my patches. When resolving the conflict, I
moved the paragraph up in the wrong definition: Should have been for
nbd-server-start, but I did it for NbdServerOptions (where it is still
at the bottom in master).

I'll fix up the broken commit instead of applying this on top. And I'll
leave in the unintentional change, because it actually makes sense, too.

Kevin

Re: [PATCH] block/export: fix QAPI doc indentation style violation

[Philippe Mathieu-Daudé]

On 10/1/20 3:14 PM, Stefan Hajnoczi wrote:
> Since commit a69a6d4b4d4fae2e3d2506241e22a78ff1732283
> ("scripts/qapi/parser.py: improve doc comment indent handling") the QAPI
> generator emits an error when unindented text follows "Returns:".
> 
> Fix block-export.json by moving the comment to make the QAPI generator
> happy.
> 
> Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
> ---
> Based-on: git://repo.or.cz/qemu/kevin.git block
> 
>  qapi/block-export.json | 24 ++++++++++++------------
>  1 file changed, 12 insertions(+), 12 deletions(-)
> 
> diff --git a/qapi/block-export.json b/qapi/block-export.json
> index 87ac5117cd..a793e34af9 100644
> --- a/qapi/block-export.json
> +++ b/qapi/block-export.json
> @@ -39,21 +39,21 @@
>  # server will present them as named exports; for example, another
>  # QEMU instance could refer to them as "nbd:HOST:PORT:exportname=NAME".
>  #
> -# @addr: Address on which to listen.
> -# @tls-creds: ID of the TLS credentials object (since 2.6).
> -# @tls-authz: ID of the QAuthZ authorization object used to validate
> -#             the client's x509 distinguished name. This object is
> -#             is only resolved at time of use, so can be deleted and
> -#             recreated on the fly while the NBD server is active.
> -#             If missing, it will default to denying access (since 4.0).
> -# @max-connections: The maximum number of connections to allow at the same
> -#                   time, 0 for unlimited. (since 5.2; default: 0)
> -#
> -# Returns: error if the server is already running.
> -#
>  # Keep this type consistent with the NbdServerOptions type. The only intended
>  # difference is using SocketAddressLegacy instead of SocketAddress.
>  #
> +# @addr: Address on which to listen.
> +# @tls-creds: ID of the TLS credentials object (since 2.6).
> +# @tls-authz: ID of the QAuthZ authorization object used to validate
> +#             the client's x509 distinguished name. This object is
> +#             is only resolved at time of use, so can be deleted and
> +#             recreated on the fly while the NBD server is active.
> +#             If missing, it will default to denying access (since 4.0).
> +# @max-connections: The maximum number of connections to allow at the same
> +#                   time, 0 for unlimited. (since 5.2; default: 0)
> +#
> +# Returns: error if the server is already running.
> +#
>  # Since: 1.3.0
>  ##
>  { 'command': 'nbd-server-start',
> 

Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com>

Re: [PATCH] block/export: fix QAPI doc indentation style violation

[Peter Maydell]

On Thu, 1 Oct 2020 at 14:18, Stefan Hajnoczi <stefanha@redhat.com> wrote:
>
> Since commit a69a6d4b4d4fae2e3d2506241e22a78ff1732283
> ("scripts/qapi/parser.py: improve doc comment indent handling") the QAPI
> generator emits an error when unindented text follows "Returns:".

> -# @addr: Address on which to listen.
> -# @tls-creds: ID of the TLS credentials object (since 2.6).
> -# @tls-authz: ID of the QAuthZ authorization object used to validate
> -#             the client's x509 distinguished name. This object is
> -#             is only resolved at time of use, so can be deleted and
> -#             recreated on the fly while the NBD server is active.
> -#             If missing, it will default to denying access (since 4.0).
> -# @max-connections: The maximum number of connections to allow at the same
> -#                   time, 0 for unlimited. (since 5.2; default: 0)
> -#
> -# Returns: error if the server is already running.
> -#
>  # Keep this type consistent with the NbdServerOptions type. The only intended
>  # difference is using SocketAddressLegacy instead of SocketAddress.

Note that the reason why the generator complains is because
according to the doc-comment structure this paragraph
("Keep this type...") is actually part of the Returns: section.
This is the same as it has always been; it's just that now the
generator wants the indent to match the structure.

Given the contents of the paragraph, it clearly wasn't intentional
that it be part of the Returns: section, so moving the text is
the right thing.

thanks
-- PMM