Re: [Qemu-devel] [PATCH 6/7] error: Revamp interface documentation

[Eric Blake <eblake@redhat.com>]

[-- Attachment #1: Type: text/plain, Size: 1850 bytes --]

On 06/22/2015 01:26 PM, Markus Armbruster wrote:
> Signed-off-by: Markus Armbruster <armbru@redhat.com>
> ---
>  include/qapi/error.h | 176 ++++++++++++++++++++++++++++++++++++---------------
>  1 file changed, 126 insertions(+), 50 deletions(-)
> 
> diff --git a/include/qapi/error.h b/include/qapi/error.h
> index 8c3a7dd..9466b09 100644
> --- a/include/qapi/error.h
> +++ b/include/qapi/error.h
> @@ -2,13 +2,75 @@
>   * QEMU Error Objects
>   *
>   * Copyright IBM, Corp. 2011
> + * Copyright (C) 2011-2015 Red Hat, Inc.
>   *
>   * Authors:
>   *  Anthony Liguori   <aliguori@us.ibm.com>
> + *  Markus Armbruster <armbru@redhat.com>,

Trailing comma, but not intermediate, looks weird.

>   *
>   * This work is licensed under the terms of the GNU LGPL, version 2.  See
>   * the COPYING.LIB file in the top-level directory.
>   */
> +
> +/*
> + * Error reporting system losely patterned after Glib's GError.

s/losely/loosely/


> + *
> + * Receive an error and pass it on to the caller

s/$/:/

> + *
> + * But when all you do with the error is passing it on, please use

s/passing/pass/


> +/*
> + * Propagate error object (if any) from @local_err to @dst_errp.
> + * If @local_err is NULL, do nothing (because there's nothing to
> + * propagate).
> + * Else, if @dst_errp is NULL, errors are being ignored.  Free the
> + * error object.
> + * Else, if @dst_errp, is &error_abort, print a suitable message and

s/dst_errp,/dst_errp/

> -/**
> - * Free an error object.
> +/*
> + * Free @err.
>   */
>  void error_free(Error *err);

Is error_free(NULL) safe? Worth documenting (because it affects
paradigms used in cleanup labels).

Overall, a definite improvement.

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


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 604 bytes --]