Re: [Qemu-devel] [PATCH v2 26/29] docs: Correct outdated information on QAPI

[Michael Roth]

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
>