Re: [PATCH 3/3] docs/doxygen: doxygen documentation for grant_table.h

[Luca Fancellu <luca.fancellu@xxxxxxx>]

> On 7 Apr 2021, at 14:56, Julien Grall <julien@xxxxxxx> wrote:
> 
> Hi Luca,
> 
> On 07/04/2021 14:19, Luca Fancellu wrote:
>>> On 7 Apr 2021, at 14:13, Julien Grall <julien@xxxxxxx> wrote:
>>> 
>>> Hi,
>>> 
>>> On 06/04/2021 11:36, Luca Fancellu wrote:
>>>> Modification to include/public/grant_table.h:
>>>> 1) Change anonymous structure to be named structure,
>>>>    because doxygen can't deal with them.
>>> 
>>> What do you mean by can't deal with them? I had a quick try with doxygen 
>>> build and couldn't find any failure (although I haven't looked at the 
>>> output).
>>> 
>> Hi Julien,
>> The problem is that Doxygen can’t generate proper documentation for 
>> anonymous union/structure, it ends up with warning and/or producing wrong 
>> documentation like
>> changing names or giving field description to the wrong field.
> 
> I might do something wrong because I cannot spot any significant difference 
> in the doxygen ouput if I switch back to anonymous union. Would you mind to 
> post more details (such as a diff) on how doxygen doesn't generate properly 
> documentation?
> 

Hi Julien,

Here the explanation of the problem: 
https://vovkos.github.io/doxyrest/manual/unnamed-structs.html

Clearly the proposed solution is not suitable because they are just hiding the 
anonymous union/struct field from the documentation.

I did two test:

1) with the anonymous structure:

struct gnttab_cache_flush {
   union {
       uint64_t dev_bus_addr;
       grant_ref_t ref;
   } a;

I get a warning from sphinx (because the XML output of Doxygen is not in a good 
shape) when I generate the documentation, here follow the output:

$ make -C docs XEN_TARGET_ARCH="arm64" sphinx-html
make: Entering directory '/home/user/prj_xen/xen/docs'
Generating xen.doxyfile
mv xen.doxyfile.tmp xen.doxyfile
Generating doxygen_input.h
/usr/bin/doxygen xen.doxyfile
Generating hypercall-interfaces/index.rst
XEN_ROOT=/home/user/prj_xen/xen /usr/bin/sphinx-build -b html . sphinx/html
Running Sphinx v1.6.7
making output directory...
loading pickled environment... not yet created
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 21 source files that are out of date
updating environment: 21 added, 0 changed, 0 removed
reading sources... [100%] misc/xen-makefiles/makefiles
/home/user/prj_xen/xen/docs/hypercall-interfaces/arm64/grant_tables.rst:6: 
WARNING: Invalid definition: Expected end of definition. [error at 18]
  gnttab_cache_flush.a
  ------------------^
looking for now-outdated files... none found
pickling environment... done
checking consistency... 
/home/user/prj_xen/xen/docs/hypercall-interfaces/arm32.rst: WARNING: document 
isn't included in any toctree
/home/user/prj_xen/xen/docs/hypercall-interfaces/x86_64.rst: WARNING: document 
isn't included in any toctree
/home/user/prj_xen/xen/docs/misc/kconfig.rst: WARNING: document isn't included 
in any toctree
/home/user/prj_xen/xen/docs/misc/kconfig-language.rst: WARNING: document isn't 
included in any toctree
/home/user/prj_xen/xen/docs/misc/kconfig-macro-language.rst: WARNING: document 
isn't included in any toctree
/home/user/prj_xen/xen/docs/misc/xen-makefiles/makefiles.rst: WARNING: document 
isn't included in any toctree
done
preparing documents... done
writing output... [100%] misc/xen-makefiles/makefiles
generating indices... genindex
writing additional pages... search
copying images... [100%] admin-guide/xen-overview.drawio.svg
copying static files... done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded, 7 warnings.
make: Leaving directory '/home/user/prj_xen/xen/docs’

And checking the generated html page 
html/hypercall-interfaces/arm64/grant_tables.html you can see that there is a 
union without name or fields right above "union 
__guest_handle_gnttab_cache_flush_t".

2) without the anonymous structure:

struct gnttab_cache_flush {
-    union {
+    union a {
       uint64_t dev_bus_addr;
       grant_ref_t ref;
   } a;

I don’t get the warning from sphinx and looking in the 
html/hypercall-interfaces/arm64/grant_tables.html page I can see the proper 
documentation for the union a right above "union 
__guest_handle_gnttab_cache_flush_t”.

Let me know if you get different results.

Cheers,
Luca

> Cheers,
> 
> -- 
> Julien Grall