[libvirt] How to generate better API documentation?

[Martin Kletzander]

On Mon, Jan 16, 2017 at 09:17:03AM +0000, Daniel P. Berrange wrote:
>On Mon, Jan 16, 2017 at 08:24:25AM +0100, Michal Privoznik wrote:
>> Dear list,
>>
>> now that we more or less agreed to use some new features (i.e. automatic free() when a variable goes out of the scope [1]), and with our NEWS efforts, do you think it is finally the right time to fix generation of our API docs too?
>>
>> What I mean? Look here: [2] People use '@variable' notation hoping that the generator will put a link there. Or that our generator would allow us to:
>>
>> typedef enum {
>>  A = X,
>>  B = Y,
>>  C = Z,
>> # ifdef VIR_ENUM_SENTINELS
>>  VIR_ENUM_LAST
>> # endif
>> } virEnum;
>>
>> where X, Y, Z come from another enum.
>>
>> Long story short, our documentation generator has a lot of bugs. What if
>> instead of putting our effort in fixing it we would switch to something
>> that is already available on the market? gtk-doc, doxygen, etc. Personally,
>> I don't have any preference. Just want to know what your opinion is.
>
>To me the key factor is what the end result looks like, how easy it is to
>navigate & find stuff. From that POV doxygen is ruled out as the HTML it
>generates is just awful - I despair every time i find a project which has
>use doxygen for its API docs :-(
>
>gtk-doc is pretty good in this respect, but the limitation is that they do
>not try to support every possible C style - they expect you to write code
>in a gobject like style. I can't tell offhand if libvirt is close enough
>to work with gtk-doc or not - I do know that QEMU failed. It is something
>you'd just have to try and see if it works, and also see if the result is
>better than what we have of course.
>
>> Again, if I get a green light I can put it onto the list of GSoC projects [3].
>
>I'm not sure this is  a good idea, because I think there's a high chance
>that you'd start the effort only to determine we should stick with what
>we have already, which would not make for a hugely successful GSoC project.
>

Actually, comparison of documentation tools can be successful even if we
don't use any at the end.  If there was a value for us (e.g. we know
what we want to use), then the project us successful.  And cleaning up
some parts of the code/comments so that it is usable by the tools is
only part of the job.  Automatic generation of docs is something they
would need to set up for each of the tools, so it would be a value for
us as well.

>Regards,
>Daniel
>--
>|: http://berrange.com      -o-    http://www.flickr.com/photos/dberrange/ :|
>|: http://libvirt.org              -o-             http://virt-manager.org :|
>|: http://entangle-photo.org       -o-    http://search.cpan.org/~danberr/ :|
>
>--
>libvir-list mailing list
>libvir-list at redhat.com
>https://www.redhat.com/mailman/listinfo/libvir-list
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: Digital signature
URL: <http://listman.redhat.com/archives/libvir-list/attachments/20170116/9bbf22eb/attachment-0001.sig>