Re: [Qemu-devel] [PATCH v2 1/4] sdcard: Update the SDState documentation

[Peter Maydell]

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

(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 '/**').

thanks
-- PMM