On 05/14/2018 12:49 PM, Peter Maydell wrote: > On 10 May 2018 at 01:24, Philippe Mathieu-Daudé <f4...@amsat.org> wrote: >> On 05/09/2018 12:42 PM, Alistair Francis wrote: >>> On Tue, May 8, 2018 at 11:01 PM, Philippe Mathieu-Daudé <f4...@amsat.org> >>> 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.
