[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Qemu-devel] [PATCH v2 1/4] sdcard: Update the SDState documentation
From: |
Philippe Mathieu-Daudé |
Subject: |
Re: [Qemu-devel] [PATCH v2 1/4] sdcard: Update the SDState documentation |
Date: |
Mon, 14 May 2018 14:07:20 -0300 |
User-agent: |
Mozilla/5.0 (X11; Linux x86_64; rv:52.0) Gecko/20100101 Thunderbird/52.7.0 |
On 05/14/2018 12:49 PM, Peter Maydell wrote:
> On 10 May 2018 at 01:24, Philippe Mathieu-Daudé <address@hidden> wrote:
>> On 05/09/2018 12:42 PM, Alistair Francis wrote:
>>> On Tue, May 8, 2018 at 11:01 PM, Philippe Mathieu-Daudé <address@hidden>
>>> wrote:
>>>> Add more descriptive comments to keep a clear separation
>>>> between static property vs runtime changeable.
>
>>> Why do we need a # here?
>>
>> I used the CPUState as a documentation example, but this might not be
>> the correct use...
>
> Our doc-comment syntax is rather inconsistent, because we've never
> actually run a tool over it to autogenerate documentation from the
> comments, and so there hasn't been anything syntax-checking them.
> The original intention for the syntax was gtkdoc, I think, where
> a leading '#' indicates a symbol that isn't a function, constant or
> parameter. However, I think the most recent consensus is that we
> should use kernel-doc format, which is similar but doesn't use the
> '#' markup:
> https://www.kernel.org/doc/Documentation/kernel-doc-nano-HOWTO.txt
Ok, I'll use this guide from now on.
> (The plan being that as we switch over to Sphinx for our docs
> tool workflow we can use the kernel's integration of kernel-doc
> into sphinx.)
>
> For this structure in particular, it is not a public struct,
> but local to a .c file. I think that for those there is not
> really any point in having any kind of doc-comment markup in
> it at all (ie no '#', no leading '/**').
Ok.
[Qemu-devel] [PATCH v2 3/4] sdcard: Implement the UHS-I SWITCH_FUNCTION entries (Spec v3), Philippe Mathieu-Daudé, 2018/05/09
[Qemu-devel] [PATCH v2 4/4] sdcard: Add a 'uhs' property, update the OCR register ACCEPT_SWITCH_1V8 bit, Philippe Mathieu-Daudé, 2018/05/09