Re: [Qemu-devel] [PATCH 0/3] cutils: Cleanup, improve documentation - Philippe Mathieu-Daudé

From: "Philippe Mathieu-Daudé" <philmd@redhat.com>
To: qemu-devel@nongnu.org, Peter Maydell <peter.maydell@linaro.org>
Cc: fam@euphon.net, david@redhat.com, qemu-trivial@nongnu.org,
	cohuck@redhat.com, armbru@redhat.com, mdroth@linux.vnet.ibm.com,
	kraxel@redhat.com, pbonzini@redhat.com
Subject: Re: [Qemu-devel] [PATCH 0/3] cutils: Cleanup, improve documentation
Date: Thu, 3 Jan 2019 10:04:29 +0100	[thread overview]
Message-ID: <e122954c-760c-47ac-3858-1c25e0b2f9ff@redhat.com> (raw)
In-Reply-To: <154645087925.9907.8533035759502851896@02a1dbf831e2>

On 1/2/19 6:41 PM, no-reply@patchew.org wrote:
> Patchew URL: https://patchew.org/QEMU/20181226171538.21984-1-philmd@redhat.com/
[...]> === OUTPUT BEGIN ===
> Checking PATCH 1/3: util/cutils: Move size_to_str() from "qemu-common.h" to "cutils.h"...
> WARNING: Block comments use a leading /* on a separate line
> #42: FILE: include/qemu/cutils.h:160:
> +/**

I believe this warning is incorrect, since we use the /** marking for
Doxygen generated documentation. The offending comment is:

  /**
   * size_to_str:
   *
   * Return human readable string for size @val.
   * Use IEC binary units like KiB, MiB, and so forth.
   *
   * @val: The value to format.
   *       Can be anything that uint64_t allows (no more than "16 EiB").
   *
   * Caller is responsible for passing it to g_free().
   */
   char *size_to_str(uint64_t val);

Am I missing something?

> Checking PATCH 2/3: util/cutils: Move ctype macros to "cutils.h"...
> WARNING: Block comments use a leading /* on a separate line
> #100: FILE: include/qemu/cutils.h:6:
> +/** unsigned ctype macros:
> 
> ERROR: code indent should never use tabs
> #108: FILE: include/qemu/cutils.h:14:
> +#define qemu_isalnum(c)^I^Iisalnum((unsigned char)(c))$

OK, this is code movement I forgot to fix :/

> Checking PATCH 3/3: util/cutils: Move function documentations to the header...
> WARNING: Block comments use a leading /* on a separate line
> #73: FILE: include/qemu/cutils.h:156:
> +/**
> 
> WARNING: Block comments use a leading /* on a separate line
> #95: FILE: include/qemu/cutils.h:179:
> +/**
> 
> WARNING: Block comments use a leading /* on a separate line
> #124: FILE: include/qemu/cutils.h:208:
> +/**
> 
> WARNING: Block comments use a leading /* on a separate line
> #154: FILE: include/qemu/cutils.h:238:
> +/**
> 
> WARNING: Block comments use a leading /* on a separate line
> #183: FILE: include/qemu/cutils.h:267:
> +/**
> 
> WARNING: Block comments use a leading /* on a separate line
> #214: FILE: include/qemu/cutils.h:298:
> +/**
> 
> WARNING: Block comments use a leading /* on a separate line
> #225: FILE: include/qemu/cutils.h:309:
> +/**
> 
> WARNING: Block comments use a leading /* on a separate line
> #235: FILE: include/qemu/cutils.h:319:
> +/**
> 
> WARNING: Block comments use a leading /* on a separate line
> #263: FILE: include/qemu/cutils.h:347:
> +/**
> 
> WARNING: Block comments use a leading /* on a separate line
> #273: FILE: include/qemu/cutils.h:357:
> +/**
> 
> WARNING: Block comments use a leading /* on a separate line
> #304: FILE: include/qemu/cutils.h:388:
> +/**