Open lrineau opened 6 years ago
I've only been using DOXYGEN_RUNNING
and \cond SKIP_IN_MANUAL
. Basically, the way I'm using it:
DOXYGEN_RUNNING
is for when the documentation of a variable/function header differs from it's actual code. For example
#ifdef DOXYGEN_RUNNING
typedef unspecified_type Index;
#else
typedef boost::uint32_t Index;
#endif
\cond SKIP_IN_MANUAL
I use to surround undocumented functions (althought using the #ifdef DOXYGEN_RUNNING
macro would do the same job, it seems cleaner to me than leaving #if
conditions everywhere, and you can't write a code-error with it as it's purely commentary).
I don't know what the other ones are used for.
I've only been using
DOXYGEN_RUNNING
and\cond SKIP_IN_MANUAL
. Basically, the way I'm using it: [...]
I use DOXYGEN_RUNNING
and \cond DEVELOPERS
, the same way. We just disagree on the keyword after \cond
.
In PR #2609, @sloriot has replaced all uses of \internal
by \cond
, and has unified the uses of \cond
by always having the label SKIP_IN_MANUAL
, that way:
\cond SKIP_IN_MANUAL
I disagree.
\internal
is very convenient to use: only one command, \internal
, without a corresponding "end-tag".\cond DEVELOPERS
has a different meaning from \cond SKIP_IN_MANUAL
:
\cond SKIP_IN_MANUAL
) seems equivalent to #ifdef DOXYGEN_RUNNING
. It means that no matter what we do not want that in the manual.DEVELOPER
, or INTERNAL
(or \internal`) seems to indicate a part of the documentation that is for the eyes of developers only.So in my opinion the discussion is not over, and I would not like that PR #2609 is merged. I think we document different ways, depending of the intent ("remove from the doc", or "for developers only").
I also suggest that our CMake scripts allows to compile the "internal" documentation, by activating at the same time \internal
and \cond <the-same-we-choose-for-interal-doc>
.
In our guidelines, I think we should document three things:
DOXYGEN_RUNNING
.DOXYGEN_RUNNING
,\cond
or \if
, and for that use we could choose one common identifier, such as: SKIP_IN_MANUAL
.\internal
, because that is very convenient to use,\cond
or \if
with a special identifier that maybe be unified.For the third usage (manual-for-developers), there could be a CMake option that activates at the same time \internal
and the \cond
sections.
I'm personally not going to read any developer doc directly in a html file, I'd better read directly the code. The major issue being that those for developer only functions will be rendered in the manual like any other function as can be seen in the following screenshot:
I understand your point and things would have been different if a thing similar to TODO was generated (that is a page where every \internal would have been gathered).
I have already used Doxygen to help reading a code, by using CALL_GRAPH
, CALLER_GRAPH
, and EXTRACT_ALL
. The CMake option could also activate those options.
I am writing of piece of documentation for Mesh_3, using the "inline" method: having the documentation of a class directly in its header, in
Mesh_3/ include/CGAL/
(by opposition to having a dedicated file inMesh_3/doc/ Mesh_3/CGAL/
).There are public types and methods that I do not want to document. To "hide" those methods from the documentation, I have already found three different ways:
Using
#ifdef/#ifndef DOXYGEN_RUNNING
Using the Doxygen command
\internal
Using the Doxygen pair of commands
\cond DEVELOPER
and\endcond
(whereDEVELOPER
is a string of your choice).In CGAL,
DOXYGEN_RUNNING
is used 200 times,\internal
is used 15 times,\cond
is used with multiple strings:\cond SKIP
\cond SKIP_DOXYGEN
\cond SKIP_IN_DOC
\cond
(without keyword)\cond SKIP_FROM_MANUAL
\cond CGAL_BEGIN_END
\cond DEVELOPERS
\cond CGAL_DOCUMENT_INTERNALS
\cond CGAL_DOCUMENT_INTERNAL
\cond SKIP_IN_MANUAL
I think we should write recommandations. Currently, our guidelines mention the three possibilities but I think we should try to unify.
Addition:
\internal
cannot be used to skip a member function entirely. But only parts of a comment block.