From mboxrd@z Thu Jan  1 00:00:00 1970
Received: from eggs.gnu.org ([2001:4830:134:3::10]:53163)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <peter.maydell@linaro.org>) id 1VMCvl-00011S-KG
	for qemu-devel@nongnu.org; Wed, 18 Sep 2013 04:16:18 -0400
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <peter.maydell@linaro.org>) id 1VMCvg-0003vv-7Z
	for qemu-devel@nongnu.org; Wed, 18 Sep 2013 04:16:13 -0400
Received: from mail-la0-f54.google.com ([209.85.215.54]:36762)
	by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <peter.maydell@linaro.org>) id 1VMCvf-0003vr-WF
	for qemu-devel@nongnu.org; Wed, 18 Sep 2013 04:16:08 -0400
Received: by mail-la0-f54.google.com with SMTP id ea20so5375226lab.13
	for <qemu-devel@nongnu.org>; Wed, 18 Sep 2013 01:16:07 -0700 (PDT)
MIME-Version: 1.0
In-Reply-To: <52395F88.7000203@ozlabs.ru>
References: <1379478118-20448-1-git-send-email-aik@ozlabs.ru>
	<CAFEAcA9o5CQcSFNtCsJdLEeH=nipXta=bDsz6CwdAe0NSbZORQ@mail.gmail.com>
	<52395A5E.2010006@ozlabs.ru>
	<CAFEAcA-yhet65070CB0is8v17i9m+DNjXntcG=Ze4atDrRqcBw@mail.gmail.com>
	<52395F88.7000203@ozlabs.ru>
From: Peter Maydell <peter.maydell@linaro.org>
Date: Wed, 18 Sep 2013 17:15:47 +0900
Message-ID: <CAFEAcA-B5MrPLVzqgon654oycfwoenLfdNP=FpSiWNuev2Wobg@mail.gmail.com>
Content-Type: text/plain; charset=UTF-8
Subject: Re: [Qemu-devel] [PATCH] kvm: add set_one_reg/get_one_reg
List-Id: <qemu-devel.nongnu.org>
List-Unsubscribe: <https://lists.nongnu.org/mailman/options/qemu-devel>,
	<mailto:qemu-devel-request@nongnu.org?subject=unsubscribe>
List-Archive: <http://lists.nongnu.org/archive/html/qemu-devel>
List-Post: <mailto:qemu-devel@nongnu.org>
List-Help: <mailto:qemu-devel-request@nongnu.org?subject=help>
List-Subscribe: <https://lists.nongnu.org/mailman/listinfo/qemu-devel>,
	<mailto:qemu-devel-request@nongnu.org?subject=subscribe>
To: Alexey Kardashevskiy <aik@ozlabs.ru>
Cc: Paolo Bonzini <pbonzini@redhat.com>, QEMU Developers <qemu-devel@nongnu.org>, Alexander Graf <agraf@suse.de>

On 18 September 2013 17:08, Alexey Kardashevskiy <aik@ozlabs.ru> wrote:
> On 09/18/2013 05:59 PM, Peter Maydell wrote:
> It would be awesome if you just gave me any really good example of what you
> expect from such a comment as kvm-all.c does not have any whatsoever. And
> pci.c does not. And exec.c does not. But I am sure there is some as
> it cannot possibly be me who starts making such comments in qemu. Thanks.

Yes, we have a lot of preexisting undocumented functions. It's
very common in QEMU for existing code not to be up to preferred
standards; you can't use current code as a yardstick for "good enough
to pass code review".

The example I usually crib from for formatting is the extract/deposit
APIs in include/qemu/bitops.h. include/exec/memory.h is also well
documented.

-- PMM