/*!

\page devman_namespaces Namespaces

\author Stefan Schirra

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 `-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

All names introduced by \cgal should be in namespace `CGAL`, <I>e.g.</I>: 
\code{.cpp}
#include <something>

namespace CGAL {

class My_new_cgal_class {};

My_new_cgal_class 
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`.

\section Developer_manualNamespaceinternal Namespace internal

All names introduced by \cgal which are not documented to the user
should be under an `internal` subnamespace of `CGAL`, <I>e.g.</I>:
\code{.cpp}
namespace CGAL { namespace internal {

class My_undocumented_class {};

void my_new_function( My_undocumented_class& );

}} // namespace CGAL::internal

namespace CGAL { namespace internal { namespace Package { namespace tags {

class Some_further_class_local_to_Package;

}}}} // namespace CGAL::internal::Package::tags
\endcode

\section Developer_manualNoteonglobaltemplatefunctions Note on global template functions

According to the resolutions of the following issues in the forthcoming
\cpp-standard (
    <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#225">225</a>,
    <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#226">226</a>
    <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#229">229</a>.
):
<TT>Unless otherwise specified, no global or non-member function in the standard library 
shall use a function from another namespace which is found through argument-dependent
name lookup
</TT>, the namespace `CGAL::NTS` does not need to be used anymore 
(currently `CGAL_NTS` macro boils down to `CGAL::`).

\section Developer_manualRequirementsandrecommendations_1 Requirements and recommendations

Requirements:
<UL>
<LI>all names defined by \cgal are in namespace `CGAL`
  (including namespaces nested in namespace `CGAL`).
<LI>explicitly prefix calls to template functions of CGAL
(such as `square`, `sign`, `abs`,  \f$ \dots\f$ ) by `CGAL::`
to ensure the functions used are the one from \cgal and not one from another
library. If you want to allow an optimized function from another library
to be used, then you should not qualify the call and document it explicitly
 (if appropriate).
</UL>

*/
