mirror of https://github.com/CGAL/cgal
Developer Manual: trivial fixes (#8883)
## Summary of Changes Fix that functions shall be written with `()`. Removed an example with the no longer existing `Window_stream` This part of the manual needs a real review, as a lot is now directly on github. * License and copyright ownership: unchanged
This commit is contained in:
Sebastien Loriot
GitHub
commit
0392062827
|
|
@ -30,7 +30,7 @@ there are <I>convincing</I> reasons.
|
|||
<LI>Words in the names of concepts (<I>e.g.</I>, template parameters)
|
||||
should be separated using capital letters. The only use of underscores
|
||||
in concept names is before the dimension suffix. For example, one
|
||||
should use a name such as ConvexHullTraits_2 for the concept
|
||||
should use a name such as `ConvexHullTraits_2` for the concept
|
||||
in contrast to `Convex_hull_traits_2` for the name of the class that
|
||||
is a model of this concept. This different naming scheme for concepts
|
||||
and classes was adopted mainly for two reasons (a) it is consistent with
|
||||
|
|
@ -49,10 +49,10 @@ there are <I>convincing</I> reasons.
|
|||
<LI>The first word of a class or enumeration name should be capitalized
|
||||
(<I>e.g.</I>, `Quotient`, `Orientation`).
|
||||
<LI>Function names are in lowercase
|
||||
(<I>e.g.</I>, `is_zero`).
|
||||
(<I>e.g.</I>, `is_zero()`).
|
||||
<LI>Boolean function names should begin with a verb. For example, use
|
||||
`is_empty` instead of simply `empty` and
|
||||
`has_on_bounded_side` instead of `on_bounded_side`.
|
||||
`is_empty()` instead of simply `empty()` and
|
||||
`has_on_bounded_side()` instead of `on_bounded_side()`.
|
||||
<LI>Names of macros should begin with the prefix `CGAL_`.
|
||||
|
||||
</UL>
|
||||
|
|
@ -72,23 +72,23 @@ there are <I>convincing</I> reasons.
|
|||
|
||||
<UL>
|
||||
<LI>Names for geometric data structures and algorithms should follow
|
||||
the "spirit" of the rules given so far, <I>e.g.</I> a data structure for
|
||||
the "spirit" of the rules given so far, <I>e.g.</I>, a data structure for
|
||||
triangulations in the plane is named `Triangulation_2`, and a
|
||||
convex hull algorithm in 3-space is named `convex_hull_3`.
|
||||
convex hull algorithm in 3-space is named `convex_hull_3()`.
|
||||
<LI>Member functions realizing predicates should start with `is_` or
|
||||
`has_`, <I>e.g.</I> the data structure `Min_ellipse_2` has member
|
||||
functions `is_empty` and `has_on_bounded_side`.
|
||||
`has_`, <I>e.g.</I>, the data structure `Min_ellipse_2` has member
|
||||
functions `is_empty()` and `has_on_bounded_side()`.
|
||||
<LI>Access to data structures is given via iterators and
|
||||
circulators (Chapter \ref devman_iterators_and_circulators ).
|
||||
For iterators and functions
|
||||
returning them we extend
|
||||
the \stl names with a prefix describing the items to be accessed.
|
||||
For example, the functions `vertices_begin` and `vertices_end`
|
||||
For example, the functions `vertices_begin()` and `vertices_end()`
|
||||
return a `Vertex_iterator`. (Note that we use the name of the items
|
||||
in singular for the iterator type name and in plural for the functions
|
||||
returning the iterator.) Names related to circulators are handled
|
||||
similarly, using the suffix `_circulator`. For example, the
|
||||
function `edges_circulator` returns an `Edge_circulator`.
|
||||
function `edges_circulator()` returns an `Edge_circulator`.
|
||||
</UL>
|
||||
|
||||
\subsection Developer_manualKerneltraits Kernel traits
|
||||
|
|
@ -183,7 +183,7 @@ In addition, for each functor the kernel traits class has a member
|
|||
function that returns an instance of this functor. The name of this
|
||||
function should be the (uncapitalized) name of the
|
||||
functor followed by the suffix `_object`.For example, the function that returns an instance of the
|
||||
`Less_xy_2` functor is called `less_xy_2_object`.
|
||||
`Less_xy_2` functor is called `less_xy_2_object()`.
|
||||
|
||||
\subsection Developer_manualFilenames File names
|
||||
|
||||
|
|
|
|||
|
|
@ -7,8 +7,8 @@
|
|||
\section Developer_manualReferencecounting Reference counting
|
||||
|
||||
As of release 2.1, a reference counting scheme is used for
|
||||
the kernel objects in the kernels `Cartesian` and
|
||||
`Homogeneous`.
|
||||
the kernel objects in the kernels `CGAL::Cartesian` and
|
||||
`CGAL::Homogeneous`.
|
||||
All copies of an object share a common representation object storing
|
||||
the data associated with a kernel object; see \cgalFigureRef{figrefcounted}.
|
||||
|
||||
|
|
@ -19,7 +19,7 @@ of the data that we would have to copy without sharing representations.
|
|||
The drawback is an indirection in accessing the data. Such an indirection is
|
||||
bad in terms of cache efficiency.
|
||||
Thus there are also non-reference-counting kernels available
|
||||
`Simple_cartesian` and `Simple_homogeneous`.
|
||||
`CGAL::Simple_cartesian` and `CGAL::Simple_homogeneous`.
|
||||
|
||||
\cgalFigureBegin{figrefcounted,reference_counting.png}
|
||||
Objects using reference counting (bottom) share common representation; copying creates a new handle (drawn at the right) pointing to the same representation as the object copied. Without reference counting (top) all data are copied to the new object (drawn at the right);
|
||||
|
|
@ -161,13 +161,13 @@ following member functions
|
|||
to manage its internal reference counting:
|
||||
|
||||
<UL>
|
||||
<LI>`add_reference`
|
||||
<LI>`add_reference()`
|
||||
|
||||
<LI>`remove_reference`
|
||||
<LI>`remove_reference()`
|
||||
|
||||
<LI>`bool is_referenced`
|
||||
<LI>`bool is_referenced()`
|
||||
|
||||
<LI>`bool is_shared`
|
||||
<LI>`bool is_shared()`
|
||||
|
||||
</UL>
|
||||
See the UML class diagram in \cgalFigureRef{figHandleFor}.
|
||||
|
|
@ -257,7 +257,7 @@ You get this functionality by including `CGAL/Handle_for.h`
|
|||
|
||||
\section Developer_manualAllocation Allocation
|
||||
|
||||
Class `Handle_for` has two template parameters. Besides the
|
||||
Class `CGAL::Handle_for` has two template parameters. Besides the
|
||||
type of the stored object, there is also a parameter specifying an
|
||||
allocator.
|
||||
Any concrete argument must be a model for the `Allocator` concept
|
||||
|
|
|
|||
|
|
@ -150,28 +150,8 @@ and used to output values to the output stream to which it is bound.
|
|||
\cgal provides extensions of the classes `istream_iterator`
|
||||
and `ostream_iterator`. The class `CGAL::Ostream_iterator<T,Stream>`
|
||||
is an output iterator adaptor for the stream class `Stream` and value
|
||||
|
||||
type `T`. It provides output iterators that can be used to output values
|
||||
of type `T` to objects of the class `Stream`.
|
||||
For example, the following code fragment inserts a list of segments into
|
||||
a window stream (<I>i.e.</I>, it draws the segments in the window) using the
|
||||
standard copy function:
|
||||
|
||||
\code{.cpp}
|
||||
typedef CGAL::Cartesian<double> K;
|
||||
typedef K::Segment_2 Segment;
|
||||
|
||||
std::vector<Segment> segments;
|
||||
Window_stream W( 400, 400);
|
||||
|
||||
int main (int argc, char** argv)
|
||||
{
|
||||
// initialize segments
|
||||
std::copy( segments.begin(),
|
||||
segments.end(),
|
||||
CGAL::Ostream_iterator< Segment, Window_stream>( W));
|
||||
}
|
||||
\endcode
|
||||
|
||||
Likewise, the class `CGAL::Istream_iterator<T,Stream>` is an input
|
||||
iterator adaptor for the stream class `Stream` and value type `T`.
|
||||
|
|
|
|||
|
|
@ -7,17 +7,9 @@
|
|||
Names, in particular (member) function names and class names should
|
||||
be descriptive and easily remembered. So it is not surprising that
|
||||
different libraries or packages choose the same name for corresponding
|
||||
or similar classes and functions. A common approach to solving the
|
||||
naming problem is to add a prefix, for example,
|
||||
OpenGL adds `gl`
|
||||
and FLTK adds `fl`. \leda uses prefix `leda_`
|
||||
|
||||
to some extent,
|
||||
but you have to tell \leda not to make the corresponding unprefixed names
|
||||
available as well.\cgalFootnote{\cgal's makefile does this by setting \cgalFootnoteCode{-DLEDA_PREFIX}.} Initially, \cgal used
|
||||
prefix `CGAL_`.
|
||||
At the beginning of 1999, it was decided to drop prefix `CGAL_` and to
|
||||
introduce namespace `CGAL`.
|
||||
or similar classes and functions. A common approach to avoid ambiguities
|
||||
is to add a prefix, for example, OpenGL adds `gl` and FLTK adds `fl`,
|
||||
but the better alternative is the usage of `namespace`.
|
||||
|
||||
\section Developer_manualNamespaceCGAL Namespace CGAL
|
||||
|
||||
|
|
@ -34,10 +26,9 @@ my_new_function( My_new_cgal_class& );
|
|||
|
||||
} // namespace CGAL
|
||||
\endcode
|
||||
Make sure not to have include statements nested between
|
||||
<TT> namespace CGAL { </TT> and <TT> } // namespace CGAL</TT>.
|
||||
Otherwise all names defined in the file included will be
|
||||
added to namespace `CGAL`.
|
||||
Make sure not to have include statements inside the
|
||||
`namespace CGAL`. Otherwise, all names defined in the file included will be
|
||||
added to the namespace.
|
||||
|
||||
\section Developer_manualNamespaceinternal Namespace internal
|
||||
|
||||
|
|
|
|||
|
|
@ -16,7 +16,7 @@ appropriate base class interface functions (besides `draw()`).
|
|||
|
||||
\cgal has chosen a different approach, since \cgal wants to avoid large
|
||||
class hierarchies. With the \cgal
|
||||
class `Object`, you can fake a common
|
||||
class `CGAL::Object`, you can fake a common
|
||||
base class, see \cgalFigureRef{FigObject}.
|
||||
|
||||
\cgalFigureBegin{FigObject,Object.png }
|
||||
|
|
@ -24,7 +24,7 @@ UML class diagram for faked object hierarchies (since 2.2-I-4).
|
|||
\cgalFigureEnd
|
||||
|
||||
Functions having a polymorphic return type create an object of the actual
|
||||
result type and wrap it into an object of type `Object`.
|
||||
result type and wrap it into an object of type `CGAL::Object`.
|
||||
Refer to the documentation of `CGAL::Object` class for more details.
|
||||
|
||||
An alternative is to use a class handling several output iterators at the same time such as the classes `CGAL::Dispatch_output_iterator`.
|
||||
|
|
|
|||
|
|
@ -65,7 +65,7 @@ probably must be deprecated and phased out), trying not to break backward
|
|||
compatibility too much.
|
||||
|
||||
A list of reasonable Boost libraries to use in the \cgal API is
|
||||
Graph, Optional, Parameter (for packages already using it),
|
||||
Graph, Parameter (for packages already using it),
|
||||
Property Map, Smart Pointers (for packages already using it),
|
||||
Variant.
|
||||
|
||||
|
|
|
|||
|
|
@ -60,7 +60,7 @@ that (are still fairly generic and) guarantee exact predicate results and
|
|||
much higher efficiency than exact number types like arbitrary precision
|
||||
integers or rationals. The efficiency relies on the use of speedy
|
||||
floating-point arithmetic in order to filter out reliable floating-point
|
||||
computations. Interval arithmetic is largely used in such filter steps.
|
||||
computations. %Interval arithmetic is largely used in such filter steps.
|
||||
|
||||
\section Developer_manualRequirementsandrecommendations Requirements and recommendations
|
||||
|
||||
|
|
|
|||
|
|
@ -9,26 +9,6 @@ Before submitting a change for integration into \cgal it is good style
|
|||
to run the testsuite of the modified package and all packages that
|
||||
could be impacted.
|
||||
|
||||
All examples and tests in CGAL are now compatible with `ctest`. So to test all examples or all tests
|
||||
of a package, you simply need to configure with `cmake` the examples/tests of the package you want to
|
||||
test, adding the option `CGAL_ENABLE_TESTING` and setting its value to `ON`. In order to report more
|
||||
warnings, it is recommended to also add the option `CGAL_DEV_MODE` and to set it to `ON`.
|
||||
Then a call to the command `ctest` will compile and run the tests/examples.
|
||||
|
||||
|
||||
\section fullTestsuite Running the Whole Testsuite
|
||||
We describe here how to proceed to the testing of a full copy of `master` or any branch by creating a <i>flat release</i>
|
||||
(that is having a layout similar to a release rather than a branch layout with header files gathered by packages).
|
||||
|
||||
The creation of the flat release is done using the `cmake` script `cgal_create_release_with_cmake.cmake` located in the directory `Scripts/developer_scripts`.
|
||||
You can run it using the option `-P` of `cmake`: `cmake -P cgal_create_release_with_cmake.cmake`.
|
||||
For an up-to-date documentation of available options, check the comments at the beginning of the script.
|
||||
|
||||
Then for testing all examples, tests, and demos, in a build directory call `cmake` on the created release
|
||||
(the path is given by the script if not manually specified)
|
||||
|
||||
`cmake -DBUILD_TESTING=ON -DWITH_examples=ON -DWITH_tests=ON -DWITH_demos=ON ../CGAL-X.XX/`
|
||||
|
||||
Finally, a call to the command `ctest` will compile and run the tests, examples, and demos.
|
||||
For details see <a href="https://github.com/CGAL/cgal/wiki/Testing">Testing</a> on the CGAL wiki on github.
|
||||
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -19,7 +19,7 @@ sections.
|
|||
|
||||
\section secwhat_is_a_traits_class What are traits classes in CGAL?
|
||||
|
||||
The algorithms in CGAL's basic library are implemented as function templates
|
||||
The algorithms in \cgal's basic library are implemented as function templates
|
||||
or class templates, usually having a template parameter whose name contains
|
||||
the word `Traits`. This template parameter
|
||||
represents a concept and so has a corresponding set of requirements that
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@
|
|||
\cgal provides a large number of data structures and algorithms dedicated to
|
||||
various applications. Most of these data structures and algorithms can be
|
||||
combined to achieve extensive and complex geometric tasks. The tutorials aim at
|
||||
providing help and ideas on how to use CGAL beyond the simple examples of the
|
||||
providing help and ideas on how to use \cgal beyond the simple examples of the
|
||||
User Manual.
|
||||
|
||||
\section tuto_list List of Available Tutorials
|
||||
|
|
|
|||
Loading…
Reference in New Issue