Re: [Qemu-devel] Introducing GSoC project: API Documentation Generation

["Daniel P. Berrangé" <berrange@redhat.com>]

On Tue, May 21, 2019 at 05:18:36PM +0200, Markus Armbruster wrote:
> Paolo Bonzini <pbonzini@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 :|