[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Qemu-devel] [PATCH v2 26/29] docs: Correct outdated information on
From: |
Michael Roth |
Subject: |
Re: [Qemu-devel] [PATCH v2 26/29] docs: Correct outdated information on QAPI |
Date: |
Mon, 19 Feb 2018 13:35:27 -0600 |
User-agent: |
alot/0.6 |
Quoting Markus Armbruster (2018-02-11 03:36:04)
> * Fix guidance on error classes
>
> * Point to generated documentation
>
> * Drop plea for documentation, because the QAPI code generator
> enforces it since commit 3313b6124b
>
> * Minor tweaks here and there
>
> Signed-off-by: Markus Armbruster <address@hidden>
Reviewed-by: Michael Roth <address@hidden>
> ---
> docs/devel/writing-qmp-commands.txt | 25 +++++++++----------------
> docs/interop/qmp-intro.txt | 3 ++-
> 2 files changed, 11 insertions(+), 17 deletions(-)
>
> diff --git a/docs/devel/writing-qmp-commands.txt
> b/docs/devel/writing-qmp-commands.txt
> index 776b3b41ca..50385eff27 100644
> --- a/docs/devel/writing-qmp-commands.txt
> +++ b/docs/devel/writing-qmp-commands.txt
> @@ -36,9 +36,9 @@ very simple and get more complex as we progress.
> For all the examples in the next sections, the test setup is the same and is
> shown here.
>
> -First, QEMU should be started as:
> +First, QEMU should be started like this:
>
> -# /path/to/your/source/qemu [...] \
> +# qemu-system-TARGET [...] \
> -chardev socket,id=qmp,port=4444,host=localhost,server \
> -mon chardev=qmp,mode=control,pretty=on
>
> @@ -179,7 +179,7 @@ described in the "Testing" section and then send two
> commands:
> }
> }
>
> -You should see "Hello, world" and "we love qemu" in the terminal running
> qemu,
> +You should see "Hello, world" and "We love qemu" in the terminal running
> qemu,
> if you don't see these strings, then something went wrong.
>
> === Errors ===
> @@ -221,30 +221,23 @@ The QMP server's response should be:
> }
> }
>
> -As a general rule, all QMP errors should use ERROR_CLASS_GENERIC_ERROR
> -(done by default when using error_setg()). There are two exceptions to
> -this rule:
> +Note that error_setg() produces a "GenericError" class. In general,
> +all QMP errors should have that error class. There are two exceptions
> +to this rule:
>
> - 1. A non-generic ErrorClass value exists* for the failure you want to report
> - (eg. DeviceNotFound)
> + 1. To support a management application's need to recognize a specific
> + error for special handling
>
> - 2. Management applications have to take special action on the failure you
> - want to report, hence you have to add a new ErrorClass value so that they
> - can check for it
> + 2. Backward compatibility
>
> If the failure you want to report falls into one of the two cases above,
> use error_set() with a second argument of an ErrorClass value.
>
> - * All existing ErrorClass values are defined in the qapi-schema.json file
> -
> === Command Documentation ===
>
> There's only one step missing to make "hello-world"'s implementation
> complete,
> and that's its documentation in the schema file.
>
> -This is very important. No QMP command will be accepted in QEMU without
> proper
> -documentation.
> -
> There are many examples of such documentation in the schema file already, but
> here goes "hello-world"'s new entry for qapi/misc.json:
>
> diff --git a/docs/interop/qmp-intro.txt b/docs/interop/qmp-intro.txt
> index adbc94abb1..430fe1b747 100644
> --- a/docs/interop/qmp-intro.txt
> +++ b/docs/interop/qmp-intro.txt
> @@ -78,7 +78,8 @@ Escape character is '^]'.
> }
> }
>
> -Please, refer to the qapi-schema.json file for a complete command reference.
> +Please refer to docs/interop/qemu-qmp-ref.* for a complete command
> +reference, generated from qapi-schema.json.
>
> QMP wiki page
> -------------
> --
> 2.13.6
>
- [Qemu-devel] [PATCH v2 01/29] Include qapi/qmp/qerror.h exactly where needed, (continued)
- [Qemu-devel] [PATCH v2 01/29] Include qapi/qmp/qerror.h exactly where needed, Markus Armbruster, 2018/02/11
- [Qemu-devel] [PATCH v2 10/29] qapi: Touch generated files only when they change, Markus Armbruster, 2018/02/11
- [Qemu-devel] [PATCH v2 26/29] docs: Correct outdated information on QAPI, Markus Armbruster, 2018/02/11
- [Qemu-devel] [PATCH v2 28/29] Fix up dangling references to qmp-commands.* in comment and doc, Markus Armbruster, 2018/02/11
- [Qemu-devel] [PATCH v2 29/29] qapi: Don't create useless directory qapi-generated, Markus Armbruster, 2018/02/11
- [Qemu-devel] [PATCH v2 09/29] qapi-gen: Convert from getopt to argparse, Markus Armbruster, 2018/02/11