libstdc++
doxygroups.cc
1 /*
2  Copyright (C) 2001, 2002, 2005, 2008, 2009, 2010
3  Free Software Foundation, Inc.
4  See license.html for license.
5 
6  This just provides documentation for stuff that doesn't need to be in the
7  source headers themselves. It is a ".cc" file for the sole cheesy reason
8  that it triggers many different text editors into doing Nice Things when
9  typing comments. However, it is mentioned nowhere except the *cfg.in files.
10 
11  Some actual code (declarations) is exposed here, but no compiler ever
12  sees it. The decls must be visible to doxygen, and sometimes their real
13  declarations are not visible, or not visible in a way we want.
14 
15  Pieces separated by '// //' lines will usually not be presented to the
16  user on the same page.
17 */
18 
19 // // // // // // // // // // // // // // // // // // // // // // // //
20 /** @namespace std
21  * @brief ISO C++ entities toplevel namespace is std.
22 */
23 /** @namespace std::__detail
24  * @brief Implementation details not part of the namespace std interface.
25 */
26 /** @namespace std::tr1
27  * @brief ISO C++ TR1 entities toplevel namespace is std::tr1.
28 */
29 /** @namespace std::tr1::__detail
30  * @brief Implementation details not part of the namespace std::tr1 interface.
31 */
32 /** @namespace __gnu_cxx
33  * @brief GNU extensions for public use.
34 */
35 /** @namespace __gnu_cxx::__detail
36  * @brief Implementation details not part of the namespace __gnu_cxx
37  * interface.
38 */
39 /** @namespace __gnu_internal
40  * @brief GNU implemenation details, not for public use or
41  * export. Used only when anonymous namespaces cannot be substituted.
42 */
43 // // // // // // // // // // // // // // // // // // // // // // // //
44 
45 /**
46  * @defgroup extensions Extensions
47  *
48  * Components generally useful that are not part of any standard.
49  */
50 
51 /** @defgroup SGIextensions SGI
52  * @ingroup extensions
53 Because libstdc++ based its implementation of the STL subsections of
54 the library on the SGI 3.3 implementation, we inherited their extensions
55 as well.
56 
57 They are additionally documented in the
58 <a href="http://gcc.gnu.org/onlinedocs/libstdc++/documentation.html">
59 online documentation</a>, a copy of which is also shipped with the
60 library source code (in .../docs/html/documentation.html). You can also
61 read the documentation <a href="http://www.sgi.com/tech/stl/">on SGI's
62 site</a>, which is still running even though the code is not maintained.
63 
64 <strong>NB</strong> that the following notes are pulled from various
65 comments all over the place, so they may seem stilted.
66 <hr>
67 */
68 
69 /** @defgroup containers Containers
70 Containers are collections of objects.
71 
72 A container may hold any type which meets certain requirements, but the type
73 of contained object is chosen at compile time, and all objects in a given
74 container must be of the same type. (Polymorphism is possible by declaring a
75 container of pointers to a base class and then populating it with pointers to
76 instances of derived classes. Variant value types such as the @c any class
77 from <a href="http://www.boost.org/">Boost</a> can also be used.
78 
79 All contained types must be @c Assignable and @c CopyConstructible.
80 Specific containers may place additional requirements on the types of
81 their contained objects.
82 
83 Containers manage memory allocation and deallocation themselves when
84 storing your objects. The objects are destroyed when the container is
85 itself destroyed. Note that if you are storing pointers in a container,
86 @c delete is @e not automatically called on the pointers before destroying them.
87 
88 All containers must meet certain requirements, summarized in
89 <a href="tables.html">tables</a>.
90 
91 The standard containers are further refined into
92 @link sequences Sequences@endlink and
93 @link associative_containers Associative Containers@endlink.
94 @link unordered_associative_containers Unordered Associative Containers@endlink.
95 */
96 
97 /** @defgroup sequences Sequences
98  * @ingroup containers
99 Sequences arrange a collection of objects into a strictly linear order.
100 
101 The differences between sequences are usually due to one or both of the
102 following:
103  - memory management
104  - algorithmic complexity
105 
106 As an example of the first case, @c vector is required to use a contiguous
107 memory layout, while other sequences such as @c deque are not.
108 
109 The prime reason for choosing one sequence over another should be based on
110 the second category of differences, algorithmic complexity. For example, if
111 you need to perform many inserts and removals from the middle of a sequence,
112 @c list would be ideal. But if you need to perform constant-time access to
113 random elements of the sequence, then @c list should not be used.
114 
115 All sequences must meet certain requirements, summarized in
116 <a href="tables.html">tables</a>.
117 */
118 
119 /** @defgroup associative_containers Associative
120  * @ingroup containers
121 Associative containers allow fast retrieval of data based on keys.
122 
123 Each container type is parameterized on a @c Key type, and an ordering
124 relation used to sort the elements of the container.
125 
126 All associative containers must meet certain requirements, summarized in
127 <a href="tables.html">tables</a>.
128 */
129 
130 /** @defgroup unordered_associative_containers Unordered Associative
131  * @ingroup containers
132 Unordered associative containers allow fast retrieval of data based on keys.
133 
134 Each container type is parameterized on a @c Key type, a @c Hash type
135 providing a hashing functor, and an ordering relation used to sort the
136 elements of the container.
137 
138 All unordered associative containers must meet certain requirements,
139 summarized in <a href="tables.html">tables</a>. */
140 
141 /**
142  * @defgroup diagnostics Diagnostics
143  *
144  * Components for error handling, reporting, and diagnostic operations.
145  */
146 
147 /**
148  * @defgroup concurrency Concurrency
149  *
150  * Components for concurrent operations, including threads, mutexes,
151  * and condition variables.
152  */