CGAL documentation: different ways skip things from the documentation

[lrineau]

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 in Mesh_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:

1. Using #ifdef/#ifndef DOXYGEN_RUNNING

2. Using the Doxygen command \internal

3. Using the Doxygen pair of commands \cond DEVELOPER and \endcond (where
   DEVELOPER is a string of your choice).

In CGAL,

• DOXYGEN_RUNNING is used 200 times,
• \internal is used 15 times,
• and \cond is used with multiple strings:
  • 1 \cond SKIP
  • 1 \cond SKIP_DOXYGEN
  • 1 \cond SKIP_IN_DOC
  • 3 \cond (without keyword)
  • 4 \cond SKIP_FROM_MANUAL
  • 8 \cond CGAL_BEGIN_END
  • 11 \cond DEVELOPERS
  • 15 \cond CGAL_DOCUMENT_INTERNALS
  • 18 \cond CGAL_DOCUMENT_INTERNAL
  • 229 \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.

[sgiraudot]

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.

[lrineau]

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.

[lrineau]

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.

1. \internal is very convenient to use: only one command, \internal, without a corresponding "end-tag".
2. I think that \cond DEVELOPERS has a different meaning from \cond SKIP_IN_MANUAL:

• The later (\cond SKIP_IN_MANUAL) seems equivalent to #ifdef DOXYGEN_RUNNING. It means that no matter what we do not want that in the manual.
• The version using 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>.

[lrineau]

In our guidelines, I think we should document three things:

1. How to substitute something for the manual, so that Doxygen and the usual C++ compiler do not see the same code, using DOXYGEN_RUNNING.
2. How to remove something completely from the manual,

• with either conditional on DOXYGEN_RUNNING,
• or with \cond or \if, and for that use we could choose one common identifier, such as: SKIP_IN_MANUAL.

3. How to have a manual-for-developers,

• with either \internal, because that is very convenient to use,
• or \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.

[sloriot]

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).

[lrineau]

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.