[PPL-devel] Documenting the classes PolyBase, Polyhedron and NNC_Polyhedron.

[Enea Zaffanella]

Hi all.

Now that we have merged the strict branch into the main one,
we have to find a proper way of documenting classes PolyBase,
Polyhedron and NNC_Polyhedron, as far as the "user" manual is concerned.

In _theory_, PolyBase is related to implementation and it should not
appear in the user manual.

However, as things are now, almost all the methods are defined only
in PolyBase and barely inherited by the two derived classes.
This will be eventually solved by having both Polyhedron and NNC_Polyhedron
inherit in a "protected" way from the base class and then populating
the Polyhedron and NNC_Polyhedron classes of "using" directives
(hoping that Doxygen will understand them).
This way, topology mismatches will be detected at compile time.


Now, Doxygen has two configuration variables named INHERIT_DOCS
and INLINE_INHERITED_MEMBERS.
The following comes from the Doxygen manual:

==================
INHERIT_DOCS
If the INHERIT_DOCS tag is set to YES (the default) then
an undocumented member inherits the documentation from
any documented member that it reimplements.
==================
INLINE_INHERITED_MEMB
If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show
all inherited members of a class in the documentation of that class
as if those members were ordinary class members. Constructors, destructors
and assignment operators of the base classes will not be shown.
===================

These seems not enough for our goal, for 4 reasons:

  1) I am not sure that Doxygen will interpret a "using" directive as the
     redefinition of a method, so that INHERIT_DOCS may not work;

  2) according to the above explanation, INHERIT_DOCS works provided the
     underlying methods of the class PolyBase are _documented_, whereas
     in the user manual all "implementation" classes should NOT be 
documented.

  3) Even if we avoid the above problems (e.g., by using the variable
     INLINE_INHERITED MEMBERS), we would end-up having all the methods
     documented twice, once in Polyhedron and once in NNC_Polyhedron.

  4) It seems to me that protected methods are documented in any case,
     i.e., they are NOT affected by the HIDE_PRIVATE_MEMBERS variable.

Also, I cannot see handy alternatives.
A possible solution is to have class PolyBase appear in the user manual
and document all the common methods there. Also, to avoid spreading the
documentation here and there, ALL the examples should appear in the detailed
description section of the class PolyBase, included those examples that 
describe
methods implemented in the derived classes, such as the constructors, 
the conversion
functions mapping a Polyhedron into a NNC_Polyhedron and viceversa, and 
those
few dedicated methods such as is_topologically_closed().

Is anyone foreseeing better alternatives ?

Enea.