Re: Doxygen example

[Stefano Stabellini <stefano.stabellini@xxxxxxxxxx>]

Hi Bertrand,

Thanks, it made it so much easier to try it out!

I managed to use it to generate html docs for my Xen branch with the
modified in-code comments in kernel-doc format. FYI the branch is here:

http://xenbits.xenproject.org/git-http/people/sstabellini/xen-unstable.git 
hyp-docs-1


These are my findings. The good thing is that it does detect some of the
comments correctly, see for instance:

doxygen-output/html/public_2grant__table_8h.html#structgrant__entry__v1


Sometimes there are errors because the kernel-doc and doxygen formats
are not identical, for instance if you look at the generated description
of vcpu_runstate_info:

  Return information about the state and running time of a VCPU. == pointer to 
vcpu_runstate_info structure.

It looks like the syntax for fields (@field) is different for doxygen.
This kind of issues should be easy to fix.


Macros are detected, but there is no way to band together a group of
related definitions, so there is still an open issue on how we are going
to be able to provide an overview comment to explain what the group is
for. For instance, look at the comment on top of
event_channel.h:EVTCHNOP_bind_interdomain to explain the meaning of
EVTCHNOPs. I wonder where Doxygen could place it. At the moment it ends
up as the private comment of EVTCHNOP_bind_interdomain.
Another example of this issue is vcpu.h:VCPUOP_initialise.



To me the Doxygen output looks less "clear" than the kernel-doc output,
but it could be a matter of taste.


The biggest problem I spotted looking throught the generated html is
that it declares all the DEFINE_XEN_GUEST_HANDLE as "Functions" while
they are actually data structures. As an example see the list of
"Functions" under:

doxygen-output/html/public_2sched_8h.html

This is definitely something we would need to solve one way or another
if we go down the doxygen route. Even finding a way to suppress it would
be an improvement.


Cheers,

Stefano



On Wed, 9 Sep 2020, Bertrand Marquis wrote:
> Hi,
> 
> Following up on 2020-09-08 call, i did a merge request on our gitlab 
> repository to provide an example of doxygen configuration and a makefile to 
> use it.
> 
> You can find the merge request here:
> https://gitlab.com/xen-project/fusa/-/merge_requests/9
> 
> To use it, you need to have clone of xen git repository and call the build 
> using:
> make XEN_TREE=/path/to/xen/clone
> 
> This will produce an html output in doxygen-output/html/index.html that you 
> can open in a browser.
> 
> So far the outcome is that doxygen is properly finding all elements but none 
> or almost none of the comments are in the right format.
> 
> Regards
> Bertrand