Re: [Qemu-devel] [PATCH 06/36] qapi: move documentation bits in schema files

[Eric Blake]

On 09/25/2015 08:03 AM, address@hidden wrote:
> From: Marc-André Lureau <address@hidden>
> 
> Moving the remaining bits of documentation to the schema files.
> 
> Signed-off-by: Marc-André Lureau <address@hidden>
> ---
>  qapi-schema.json | 48 ++++++++++++++++++++++++++++++++++++++++++-
>  qmp-commands.hx  | 62 
> --------------------------------------------------------
>  2 files changed, 47 insertions(+), 63 deletions(-)
> 
> diff --git a/qapi-schema.json b/qapi-schema.json
> index 1383011..c8ee75d 100644
> --- a/qapi-schema.json
> +++ b/qapi-schema.json
> @@ -1,6 +1,52 @@
>  # -*- Mode: Python -*-
> +##
> +# = Introduction
> +#
> +# This document describes all commands currently supported by QMP.
> +#
> +# Most of the time their usage is exactly the same as in the user Monitor, 
> this
> +# means that any other document which also describe commands (the manpage,
> +# QEMU's manual, etc) can and should be consulted.
> +#
> +# QMP has two types of commands: regular and query commands. Regular commands
> +# usually change the Virtual Machine's state someway, while query commands 
> just
> +# return information. The sections below are divided accordingly.

Do we really still have that clean division?

> +#
> +# It's important to observe that all communication examples are formatted in
> +# a reader-friendly way, so that they're easier to understand. However, in 
> real
> +# protocol usage, they're emitted as a single line.

The server replies in a single line, but the client is free to send in
multiple lines.

> +#
> +# Also, the following notation is used to denote data flow:
> +#
> +# Example:
> +#
> +# | -> data issued by the Client
> +# | <- Server data response
> +#
> +# Please, refer to the QMP specification (QMP/qmp-spec.txt) for detailed
> +# information on the Server command and response formats.

Stale comment, pointing to the wrong file name (commit 7537fe04 moved it
from QMP/ to docs/qmp/) (and Markus has a patch pending that moves it
from docs/qmp/qmp-spec.txt to docs/qmp-spec.txt).

> +#
> +# = Stability Considerations
> +#
> +# The current QMP command set (described in this file) may be useful for a
> +# number of use cases, however it's limited and several commands have bad
> +# defined semantics, specially with regard to command completion.
> +#
> +# These problems are going to be solved incrementally in the next QEMU 
> releases
> +# and we're going to establish a deprecation policy for badly defined 
> commands.

Wow - some of this stuff has bit-rotted over time. I don't know how much
command completion we support for QMP (I guess it depends whether you
are using qmp-shell or a straight monitor connection), and while we do
still have badly defined commands, they are now the exception and we
have made a lot of progress in fixing things.

> +#
> +# If you're planning to adopt QMP, please observe the following:
> +#
> +#     1. The deprecation policy will take effect and be documented soon, 
> please
> +#        check the documentation of each used command as soon as a new 
> release of
> +#        QEMU is available

Umm, we still don't have a documented deprecation policy.

> +#
> +#     2. DO NOT rely on anything which is not explicit documented

s/explicit/explicitly/

> +#
> +#     3. Errors, in special, are not documented. Applications should NOT 
> check
> +#        for specific errors classes or data (it's strongly recommended to 
> only
> +#        check for the "error" key)
>  #
> -# QAPI Schema
>  
>  # QAPI common definitions
>  { 'include': 'qapi/common.json' }

-- 
Eric Blake   eblake redhat com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org

signature.asc
Description: OpenPGP digital signature