Re: [libvirt] How to generate better API documentation?
On Mon, Jan 16, 2017 at 09:17:03AM +, Daniel P. Berrange wrote: > > 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. kernel people have been experimenting with Sphinx for both linux/Documentation file, and inline source file documentation, https://lwn.net/Articles/692704/ Christophe signature.asc Description: PGP signature -- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list
Re: [libvirt] How to generate better API documentation?
On Mon, Jan 16, 2017 at 09:17:03AM +, 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@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list
signature.asc
Description: Digital signature
--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list
Re: [libvirt] How to generate better API documentation?
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.
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@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list
Re: [libvirt] How to generate better API documentation?
On 16.01.2017 08:24, 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.
Also, there is no link validation. For instance, I'm going through our
network docs [3] reading about trustGuestRxFilters. And the paragraph
links non-existent anchor #elementSNICS in domain XML page.
While this one can be fixed easily, checking for others would be a waste
of time.
Michal
3: http://libvirt.org/formatnetwork.html#elementsMetadata
--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list
[libvirt] How to generate better API documentation?
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.
Again, if I get a green light I can put it onto the list of GSoC projects [3].
Michal
1: https://www.redhat.com/archives/libvir-list/2017-January/msg00323.html
2:
http://libvirt.org/html/libvirt-libvirt-domain.html#virConnectDomainEventBlockJobCallback
3: http://wiki.libvirt.org/page/Google_Summer_of_Code_2017
--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list
