On 21/05/19 17:27, Peter Maydell wrote: >> Anyway. What's so special about QEMU that justifies coming up with our >> own doc syntax? Other than "we made a hash of it, and cleaning it up >> would be work". > The major problem as far as kernel-doc is concerned is that > it somewhat bakes in the kernel's style choice that the > 'struct' keyword is not hidden behind typedefs, and so it > gets a bit confused by QEMU's "use typedefs for struct types" > style. The rest, as you say, is just a matter of fixing up > our syntax errors.
Exactly, "QEMU's syntax" is supposed to be actually gtkdoc, or inspired by it, because of the similar typedef conventions. The basic components are: - the head of the doc comment is either a CamelCase type or a function name followed by parentheses - @ introduces parameters, e.g. @path - % introduces types, e.g. %DeviceState - () terminate functions, e.g. memory_region_init() - # introduces other C symbols, e.g. #NULL and they map very well to what kerneldoc tries to parse, IIRC it only requires some changes to the regular expression at the top of the file. Paolo
