[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

From: Daniel P . Berrangé
Subject: Re: [Qemu-devel] Introducing GSoC project: API Documentation Generation
Date: Tue, 21 May 2019 16:25:30 +0100
User-agent: Mutt/1.11.4 (2019-03-13)

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

|: 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 :|

reply via email to

[Prev in Thread] Current Thread [Next in Thread]