On Tue, May 21, 2019 at 05:18:36PM +0200, Markus Armbruster wrote: > Paolo Bonzini <pbonz...@redhat.com> writes: > > > On 21/05/19 10:53, Daniel P. Berrangé wrote: > [...] > >> QEMU should pick a tool which is well established / widely used & thus > >> stands a good chance of being maintained for the long term, as we don't > >> want to end up relying on abandonware in 5 years time. The kernel-doc > >> project is not widely used, but its main user is significant enough that > >> it isn't likely to die through lack of maintainers. > > > > A couple years ago I didn't have problems modifying kerneldoc for QEMU's > > syntax, it was a 10 lines patch. Unfortunately I cannot find it anymore. > > "QEMU's syntax" --- excuse me while I guffaw. > > What you (quite charitably) call "syntax", I call a habit of imitating > examples. > > 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".
There's really no such thing as "QEMU syntax" for docs comments right now AFAICT. We have used at least 4 different syntaxes across the various parts of the codebase and none seems a clear winner in terms of usage. So I assume that whatever tool we pick, the majority of work will be updating existing docs comments to follow whatever syntax is picked. Regards, Daniel -- |: https://berrange.com -o- https://www.flickr.com/photos/dberrange :| |: https://libvirt.org -o- https://fstop138.berrange.com :| |: https://entangle-photo.org -o- https://www.instagram.com/dberrange :|
