On 07/04/2021 16:29, Bertrand Marquis wrote:
Hi Ian,
On 7 Apr 2021, at 16:19, Ian Jackson <i...@xenproject.org> wrote:
Luca Fancellu writes ("Re: [PATCH 3/3] docs/doxygen: doxygen documentation for
grant_table.h"):
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.
This does not seem like it would be an impossibly hard feature to add
to doxygen.
Modifying doxygen is not really in our planned efforts and if someone does it
that would put an hard constraint on the version of doxygen possible to use.
Are you saying that anyone who want to use doxygen has to waive off the
use of anonymous union/struct? Is it the only thing doxygen can't deal with?
But is adding names to anonymous elements really an issue here ?
If we agree on names or on a convention for name the result will not impact the
code or backward compatibility.
I think the naming is only the tip of the problem. One advantage of
anymous union/struct is you make clear they are not meant to be used
outside of the context. So they should mostly be seen as an easy way to
access some part of the "parent" structure directly. Therefore, IMHO,
they don't deserve to be documented separately.
In fact, this is the first thing I noticed when building the
documentation because 'union a' was in global index.
Cheers,
--
Julien Grall
