> On 7 Apr 2021, at 14:56, Julien Grall <jul...@xen.org> wrote:
>
> Hi Luca,
>
> On 07/04/2021 14:19, Luca Fancellu wrote:
>>> On 7 Apr 2021, at 14:13, Julien Grall <jul...@xen.org> 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
