songsenand
/
cgal
mirror of https://github.com/CGAL/cgal
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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 2025-05-16 13:02:56 +02:00 committed by GitHub
parent c6aa4fea5f 206be8d951
commit 0392062827
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
11 changed files with 33 additions and 82 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
Documentation/doc/Documentation/Developer_manual/Chapter_code_format.txt
View File

@ -30,7 +30,7 @@ there are <I>convincing</I> reasons.
<LI>Words in the names of concepts (<I>e.g.</I>, template parameters) <LI>Words in the names of concepts (<I>e.g.</I>, template parameters)
should be separated using capital letters. The only use of underscores should be separated using capital letters. The only use of underscores
in concept names is before the dimension suffix. For example, one 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 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 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 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 <LI>The first word of a class or enumeration name should be capitalized
(<I>e.g.</I>, `Quotient`, `Orientation`). (<I>e.g.</I>, `Quotient`, `Orientation`).
<LI>Function names are in lowercase <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 <LI>Boolean function names should begin with a verb. For example, use
`is_empty` instead of simply `empty` and `is_empty()` instead of simply `empty()` and
`has_on_bounded_side` instead of `on_bounded_side`. `has_on_bounded_side()` instead of `on_bounded_side()`.
<LI>Names of macros should begin with the prefix `CGAL_`. <LI>Names of macros should begin with the prefix `CGAL_`.
</UL> </UL>
@ -72,23 +72,23 @@ there are <I>convincing</I> reasons.
<UL> <UL>
<LI>Names for geometric data structures and algorithms should follow <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 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 <LI>Member functions realizing predicates should start with `is_` or
`has_`, <I>e.g.</I> the data structure `Min_ellipse_2` has member `has_`, <I>e.g.</I>, the data structure `Min_ellipse_2` has member
functions `is_empty` and `has_on_bounded_side`. functions `is_empty()` and `has_on_bounded_side()`.
<LI>Access to data structures is given via iterators and <LI>Access to data structures is given via iterators and
circulators (Chapter \ref devman_iterators_and_circulators ). circulators (Chapter \ref devman_iterators_and_circulators ).
For iterators and functions For iterators and functions
returning them we extend returning them we extend
the \stl names with a prefix describing the items to be accessed. 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 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 in singular for the iterator type name and in plural for the functions
returning the iterator.) Names related to circulators are handled returning the iterator.) Names related to circulators are handled
similarly, using the suffix `_circulator`. For example, the similarly, using the suffix `_circulator`. For example, the
function `edges_circulator` returns an `Edge_circulator`. function `edges_circulator()` returns an `Edge_circulator`.
</UL> </UL>
\subsection Developer_manualKerneltraits Kernel traits \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 that returns an instance of this functor. The name of this
function should be the (uncapitalized) name of the function should be the (uncapitalized) name of the
functor followed by the suffix `_object`.For example, the function that returns an instance 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 \subsection Developer_manualFilenames File names

16
Documentation/doc/Documentation/Developer_manual/Chapter_handles.txt
View File

@ -7,8 +7,8 @@
\section Developer_manualReferencecounting Reference counting \section Developer_manualReferencecounting Reference counting
As of release 2.1, a reference counting scheme is used for As of release 2.1, a reference counting scheme is used for
the kernel objects in the kernels `Cartesian` and the kernel objects in the kernels `CGAL::Cartesian` and
`Homogeneous`. `CGAL::Homogeneous`.
All copies of an object share a common representation object storing All copies of an object share a common representation object storing
the data associated with a kernel object; see \cgalFigureRef{figrefcounted}. 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 The drawback is an indirection in accessing the data. Such an indirection is
bad in terms of cache efficiency. bad in terms of cache efficiency.
Thus there are also non-reference-counting kernels available 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} \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); 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: to manage its internal reference counting:
<UL> <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> </UL>
See the UML class diagram in \cgalFigureRef{figHandleFor}. 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 \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 type of the stored object, there is also a parameter specifying an
allocator. allocator.
Any concrete argument must be a model for the `Allocator` concept Any concrete argument must be a model for the `Allocator` concept

20
Documentation/doc/Documentation/Developer_manual/Chapter_iterators_and_circulators.txt
View File

@ -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` \cgal provides extensions of the classes `istream_iterator`
and `ostream_iterator`. The class `CGAL::Ostream_iterator<T,Stream>` and `ostream_iterator`. The class `CGAL::Ostream_iterator<T,Stream>`
is an output iterator adaptor for the stream class `Stream` and value 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 type `T`. It provides output iterators that can be used to output values
of type `T` to objects of the class `Stream`. 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 Likewise, the class `CGAL::Istream_iterator<T,Stream>` is an input
iterator adaptor for the stream class `Stream` and value type `T`. iterator adaptor for the stream class `Stream` and value type `T`.

21
Documentation/doc/Documentation/Developer_manual/Chapter_namespaces.txt
View File

@ -7,17 +7,9 @@
Names, in particular (member) function names and class names should Names, in particular (member) function names and class names should
be descriptive and easily remembered. So it is not surprising that be descriptive and easily remembered. So it is not surprising that
different libraries or packages choose the same name for corresponding different libraries or packages choose the same name for corresponding
or similar classes and functions. A common approach to solving the or similar classes and functions. A common approach to avoid ambiguities
naming problem is to add a prefix, for example, is to add a prefix, for example, OpenGL adds `gl` and FLTK adds `fl`,
OpenGL adds `gl` but the better alternative is the usage of `namespace`.
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`.
\section Developer_manualNamespaceCGAL Namespace CGAL \section Developer_manualNamespaceCGAL Namespace CGAL
@ -34,10 +26,9 @@ my_new_function( My_new_cgal_class& );
} // namespace CGAL } // namespace CGAL
\endcode \endcode
Make sure not to have include statements nested between Make sure not to have include statements inside the
<TT> namespace CGAL { </TT> and <TT> } // namespace CGAL</TT>. `namespace CGAL`. Otherwise, all names defined in the file included will be
Otherwise all names defined in the file included will be added to the namespace.
added to namespace `CGAL`.
\section Developer_manualNamespaceinternal Namespace internal \section Developer_manualNamespaceinternal Namespace internal

4
Documentation/doc/Documentation/Developer_manual/Chapter_objects.txt
View File

@ -16,7 +16,7 @@ appropriate base class interface functions (besides `draw()`).
\cgal has chosen a different approach, since \cgal wants to avoid large \cgal has chosen a different approach, since \cgal wants to avoid large
class hierarchies. With the \cgal 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}. base class, see \cgalFigureRef{FigObject}.
\cgalFigureBegin{FigObject,Object.png } \cgalFigureBegin{FigObject,Object.png }
@ -24,7 +24,7 @@ UML class diagram for faked object hierarchies (since 2.2-I-4).
\cgalFigureEnd \cgalFigureEnd
Functions having a polymorphic return type create an object of the actual 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. 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`. An alternative is to use a class handling several output iterators at the same time such as the classes `CGAL::Dispatch_output_iterator`.

2
Documentation/doc/Documentation/Developer_manual/Chapter_portability.txt
View File

@ -65,7 +65,7 @@ probably must be deprecated and phased out), trying not to break backward
compatibility too much. compatibility too much.
A list of reasonable Boost libraries to use in the \cgal API is 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), Property Map, Smart Pointers (for packages already using it),
Variant. Variant.

2
Documentation/doc/Documentation/Developer_manual/Chapter_robustness.txt
View File

@ -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 much higher efficiency than exact number types like arbitrary precision
integers or rationals. The efficiency relies on the use of speedy integers or rationals. The efficiency relies on the use of speedy
floating-point arithmetic in order to filter out reliable floating-point 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 \section Developer_manualRequirementsandrecommendations Requirements and recommendations

22
Documentation/doc/Documentation/Developer_manual/Chapter_testing.txt
View File

@ -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 to run the testsuite of the modified package and all packages that
could be impacted. could be impacted.
All examples and tests in CGAL are now compatible with `ctest`. So to test all examples or all tests For details see <a href="https://github.com/CGAL/cgal/wiki/Testing">Testing</a> on the CGAL wiki on github.
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.
*/ */

2
Documentation/doc/Documentation/Developer_manual/Chapter_traits_classes.txt
View File

@ -19,7 +19,7 @@ sections.
\section secwhat_is_a_traits_class What are traits classes in CGAL? \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 or class templates, usually having a template parameter whose name contains
the word `Traits`. This template parameter the word `Traits`. This template parameter
represents a concept and so has a corresponding set of requirements that represents a concept and so has a corresponding set of requirements that

2
Documentation/doc/Documentation/Tutorials/Tutorials.txt
View File

@ -5,7 +5,7 @@
\cgal provides a large number of data structures and algorithms dedicated to \cgal provides a large number of data structures and algorithms dedicated to
various applications. Most of these data structures and algorithms can be various applications. Most of these data structures and algorithms can be
combined to achieve extensive and complex geometric tasks. The tutorials aim at 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. User Manual.
\section tuto_list List of Available Tutorials \section tuto_list List of Available Tutorials

2
Documentation/doc/Documentation/deprecated.txt
View File

@ -2,7 +2,7 @@
\page deprecated Deprecation Notice \page deprecated Deprecation Notice
In \cgal, we are trying as much as possible not to break the backward compatibility. If we have to do it, it will be announced in the <a href="https://www.cgal.org/releases.html">release notes</a> , In \cgal, we are trying as much as possible not to break the backward compatibility. If we have to do it, it will be announced in the <a href="https://www.cgal.org/releases.html">release notes</a>,
and a solution will always be provided. When possible, we keep the deprecated API for two releases before removing it. and a solution will always be provided. When possible, we keep the deprecated API for two releases before removing it.
If you reached this page after clicking on a link, it must probably mean that the documentation page you were trying to reach If you reached this page after clicking on a link, it must probably mean that the documentation page you were trying to reach
is now deprecated. Have a look at the <a href="https://www.cgal.org/releases.html">release notes</a> for more information. is now deprecated. Have a look at the <a href="https://www.cgal.org/releases.html">release notes</a> for more information.