CGAL 6.2 - Manual: Organization of the Manual

CGAL 6.2 - Manual

Loading...
Searching...
No Matches
Organization of the Manual

Author
  CGAL Editorial Board

# 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 Package Overview 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.

# Organization of the Reference Manual

The CGAL library is a library of class templates. Consequently, we express the requirements on template arguments by specifying concepts and by providing models for concepts. See 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 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.

Figure 0.1 Models and concepts.

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 Figure 0.1 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 Concepts and Models the notion of a concept is about requirements, and it can be a required global function or a required traits class.

# Marking of Special Functionality

In this manual, you will encounter sections marked as follows.

## Advanced Features

Some functionality is considered more advanced, for example because it is relatively low-level, or requires special care to be properly used.

Advanced

Such functionality is identified this way in the manual.

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

Debugging Support

Such functionality is identified this way in the manual.

## Deprecated Code

Sometimes, the CGAL project decides that a feature is deprecated. 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.