mirror of https://github.com/CGAL/cgal
113 lines
4.5 KiB
Plaintext
113 lines
4.5 KiB
Plaintext
/*!
|
|
|
|
\page manual Organization of the Manual
|
|
\cgalAutoToc
|
|
\author %CGAL Editorial Board
|
|
|
|
\section secorganization Organization of the Manual
|
|
|
|
This manual is organized in several parts covering the many domains
|
|
of computational geometry.
|
|
Each part consists of several chapters,
|
|
and each chapter is split into a *User Manual* and a *Reference
|
|
Manual*. The User Manual gives the general idea and comes with examples.
|
|
The Reference Manual presents the \api of the various classes
|
|
and functions.
|
|
|
|
The manual has a \ref packages with a short paragraph explaining
|
|
what each package is about, what license
|
|
it has, and on which other packages it depends. It further provides
|
|
links to precompiled demo programs for the Windows platform.
|
|
|
|
The manual further has a class index, as well as a search box in the upper right of
|
|
each page.
|
|
The scope of the search box is the package you currently look at and the
|
|
packages it depends on, or it is the whole manual when you are in
|
|
a top level page such as the package overview.
|
|
|
|
\section secorganizationref Organization of the Reference Manual
|
|
|
|
The \cgal library is a library of class templates. Consequently, we express
|
|
the requirements on template arguments by specifying \em concepts
|
|
and by providing \em models for concepts. See \ref intro_concept "here"
|
|
for an explanation of concept/model.
|
|
|
|
The reference manual has pages for concepts and for models,
|
|
and just as classes can be derived from other classes, concepts
|
|
can \em refine other concepts, by adding requirements.
|
|
|
|
When a class is a model of a concept, its reference manual
|
|
page has a link to the concept, and the API is mainly documented
|
|
on the reference manual page of the concept. As a concept
|
|
may refine another concept, the full API of a class is sometimes
|
|
distributed over the pages of base classes and over the pages
|
|
of several concepts.
|
|
|
|
Let's have a look at the vertex type of 3D triangulations.
|
|
|
|
\cgalFigureBegin{Manual_Fig_concept_model,ConceptModel.svg}
|
|
Models and concepts.
|
|
\cgalFigureEnd
|
|
|
|
The class `CGAL::Triangulation_vertex_base_3` derives from
|
|
the class `CGAL::Triangulation_ds_vertex_base_3`.
|
|
The two classes are models of the concepts `TriangulationVertexBase_3`
|
|
and `TriangulationDSVertexBase_3`, respectively.
|
|
The former concept refines the latter.
|
|
|
|
In the reference manual pages of these concepts and models
|
|
only the methods and types which are not greyed in
|
|
\cgalFigureRef{Manual_Fig_concept_model} are documented.
|
|
Inherited methods are only documented in the base class.
|
|
And methods that must be implemented in order to be a
|
|
model of a concept are only documented in the concept.
|
|
|
|
As pointed out in Section \ref intro_concept "Concepts and Models"
|
|
the notion of a \em concept is about requirements,
|
|
and it can be a required global function or a required traits class.
|
|
|
|
\section markingSpecialFunctionality Marking of Special Functionality
|
|
|
|
In this manual, you will encounter sections marked as follows.
|
|
|
|
\subsection advanced_features Advanced Features
|
|
|
|
Some functionality is considered more advanced, for example because it is
|
|
relatively low-level, or requires special care to be properly used.
|
|
|
|
\cgalAdvancedBegin
|
|
Such functionality is identified this way in the manual.
|
|
\cgalAdvancedEnd
|
|
|
|
\subsection debugging_support Debugging Support Features
|
|
|
|
Usually related to advanced features that for example may not guarantee
|
|
class invariants, some functionality is provided that helps debugging,
|
|
for example by performing invariants checks on demand.
|
|
|
|
\cgalDebugBegin
|
|
Such functionality is identified this way in the manual.
|
|
\cgalDebugEnd
|
|
|
|
\subsection deprecated_code Deprecated Code
|
|
|
|
Sometimes, the \cgal project decides that a feature is <em>deprecated</em>. This means
|
|
that it still works in the current release, but it will be removed in the next,
|
|
or a subsequent release. This can happen when we have found a better way to do
|
|
something, and we would like to reduce the maintenance cost of \cgal at some
|
|
point in the future. There is a trade-off between maintaining backward
|
|
compatibility and implementing new features more easily.
|
|
|
|
In order to help users manage the changes to apply to their code, we attempt
|
|
to make \cgal code emit warnings when deprecated code is used. This can be
|
|
done using some compiler specific features. Those warnings can be disabled
|
|
by defining the macro `CGAL_NO_DEPRECATION_WARNINGS`. On top of this, we
|
|
also provide a macro, `CGAL_NO_DEPRECATED_CODE`, which, when defined,
|
|
disables all deprecated features. This allows users to easily test if their
|
|
code relies on deprecated features.
|
|
|
|
\deprecated Such functionality is identified this way in the manual.
|
|
|
|
*/
|
|
|