On 24/05/19 21:08, Eduardo Habkost wrote: > On Fri, May 24, 2019 at 08:34:23PM +0200, Paolo Bonzini wrote: >> On 23/05/19 14:20, John Snow wrote: >>> OK, if that's where we're at! I just saw the RFC from Peter Maydell and >>> assumed we were a little further along the decision making process, but >>> maybe not. I'll stay tuned. >> >> For the decision making, yes; I think there's consensus to use >> kerneldoc. For the "debugging and seeing if anything has changed in 2.5 >> years", no. >> >> Testing the patch that Eduardo posted will help Gabriel, Eduardo and >> everyone else decide whether to patch kerneldoc or rather change the API >> doc comments style. (Personally I am in favor of patching; the >> different coding conventions make using vanilla kerneldoc awkward, and >> there are several thousands of lines of existing doc comments which >> would require a transition.) > > I'd prefer to fix our doc comments instead of patching kerneldoc, > whenever possible. We don't even have a consistent doc comment > style in QEMU.
I think we *mostly* do, at least as far as the @/#/% sigils are concerned. In particular, only "#" separates the QEMU doc comment style from the kernel and it has 200+ instances vs. 6 for the kernel's '&struct foo' (all in accel/tcg/translate-all.c), so it's clear that our standard is different from the kernel in this respect. The rest of the patch is to handle typedefed structs, which again is more or less a necessity. Paolo
