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.