From: Luca Fancellu <luca.fancellu@arm.com>
To: Julien Grall <julien@xen.org>
Cc: xen-devel@lists.xenproject.org,
Bertrand Marquis <bertrand.marquis@arm.com>,
wei.chen@arm.com, Andrew Cooper <andrew.cooper3@citrix.com>,
George Dunlap <george.dunlap@citrix.com>,
Ian Jackson <iwj@xenproject.org>, Jan Beulich <jbeulich@suse.com>,
Stefano Stabellini <sstabellini@kernel.org>, Wei Liu <wl@xen.org>
Subject: Re: [PATCH 3/3] docs/doxygen: doxygen documentation for grant_table.h
Date: Wed, 7 Apr 2021 15:51:18 +0100 [thread overview]
Message-ID: <E5D03BC8-6E9E-4579-B2D8-137CC60818B9@arm.com> (raw)
In-Reply-To: <b55d2d18-c80c-5596-8ac4-d4d7099708bf@xen.org>
> On 7 Apr 2021, at 14:56, Julien Grall <julien@xen.org> wrote:
>
> Hi Luca,
>
> On 07/04/2021 14:19, Luca Fancellu wrote:
>>> On 7 Apr 2021, at 14:13, Julien Grall <julien@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
next prev parent reply other threads:[~2021-04-07 14:52 UTC|newest]
Thread overview: 34+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-04-06 10:36 [PATCH 0/3] Use Doxygen and sphinx for html documentation Luca Fancellu
2021-04-06 10:36 ` [PATCH 1/3] docs: add doxygen support " Luca Fancellu
2021-04-06 10:36 ` [PATCH 2/3] docs: hypercalls sphinx skeleton for generated html Luca Fancellu
2021-04-06 10:36 ` [PATCH 3/3] docs/doxygen: doxygen documentation for grant_table.h Luca Fancellu
2021-04-06 11:19 ` Jan Beulich
2021-04-06 21:46 ` Stefano Stabellini
2021-04-07 8:10 ` Jan Beulich
2021-04-07 8:42 ` Luca Fancellu
2021-04-07 8:58 ` Jan Beulich
2021-04-07 21:26 ` Stefano Stabellini
2021-04-08 5:59 ` Jan Beulich
2021-04-08 11:02 ` Luca Fancellu
2021-04-08 11:28 ` Jan Beulich
2021-04-08 11:40 ` Julien Grall
2021-04-08 11:50 ` Julien Grall
2021-04-08 13:13 ` Luca Fancellu
2021-04-08 11:58 ` Luca Fancellu
2021-04-07 13:13 ` Julien Grall
2021-04-07 13:19 ` Luca Fancellu
2021-04-07 13:56 ` Julien Grall
2021-04-07 14:51 ` Luca Fancellu [this message]
2021-04-07 15:19 ` Ian Jackson
2021-04-07 15:29 ` Bertrand Marquis
2021-04-07 15:54 ` Jan Beulich
2021-04-07 16:07 ` Bertrand Marquis
2021-04-07 15:55 ` Julien Grall
2021-04-07 16:06 ` Bertrand Marquis
2021-04-07 16:12 ` Ian Jackson
2021-04-06 11:53 ` [PATCH 0/3] Use Doxygen and sphinx for html documentation Andrew Cooper
2021-04-06 21:24 ` Stefano Stabellini
2021-04-07 11:15 ` Andrew Cooper
2021-04-07 13:05 ` Bertrand Marquis
2021-04-07 13:07 ` Julien Grall
2021-04-07 13:16 ` Luca Fancellu
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=E5D03BC8-6E9E-4579-B2D8-137CC60818B9@arm.com \
--to=luca.fancellu@arm.com \
--cc=andrew.cooper3@citrix.com \
--cc=bertrand.marquis@arm.com \
--cc=george.dunlap@citrix.com \
--cc=iwj@xenproject.org \
--cc=jbeulich@suse.com \
--cc=julien@xen.org \
--cc=sstabellini@kernel.org \
--cc=wei.chen@arm.com \
--cc=wl@xen.org \
--cc=xen-devel@lists.xenproject.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).