Re: [Qemu-trivial] [Qemu-devel] [PATCH v2] CODING_STYLE: Define our preferred form for multiline comments

[Peter Maydell]

On 15 June 2018 at 05:43, Thomas Huth <address@hidden> wrote:
> On 14.06.2018 22:11, John Snow wrote:
>> Do you have a proposed standard / do we have some consensus on which
>> generator tool or doc format we'd most like to see in QEMU? I could put
>> in some elbow grease to shine up the block layer if so...
>
> I remember that some years ago, somebody (I forgot who it was, sorry)
> once told me that we should use the same format in QEMU as in glib, i.e.
> GTK-Doc. But citing the GTK-Doc homepage: "For a more polished
> general-purpose documentation tool you may want to look at Doxygen" - so
> maybe that's the better choice instead.

The last round of email threads on this basically concluded that
we should use sphinx, which is what the kernel uses. So kernel-doc
comment format, and rst for standalone docs files. Some tidying
up of our current doc comments would be required (which are a bit
of a mishmash of styles plus syntax errors because we've never
done any kind of processing of them to keep us from making mistakes).

thanks
-- PMM