This is the mail archive of the
libstdc++@gcc.gnu.org
mailing list for the libstdc++ project.
[libstdc++] initial ABI doc, more updates
- From: Phil Edwards <phil at jaj dot com>
- To: libstdc++ at gcc dot gnu dot org, gcc-patches at gcc dot gnu dot org
- Date: Sat, 20 Jul 2002 02:26:10 -0400
- Subject: [libstdc++] initial ABI doc, more updates
Some little things that should have gone in the last doc patch I posted.
The s/3.3/3.4/ change to deprecated function removal (as proposed on
libstdc++/gcc lists) is here. Also, a copy of Benjamin's first pass at
explaining the library ABI issues is now in docs/html/abi.txt. There's a
commented-out link to it in documentation.html, which I'll uncomment once
we get some more info in there.
I also made some changes to the doxygen markup in some of the header files.
The "@brief" description shows up in more places than what I originally
thought, so it's a Good Thing to have.
Many of the formatting changes that were done on the STL sequences got
skipped for vector; we pick those up here.
Tested on i686-pc-linux-gnu, applied to mainline.
2002-07-20 Phil Edwards <pme@gcc.gnu.org>
* docs/html/abi.txt: New file.
* docs/html/23_containers/howto.html: Tweak vector-overhead text.
* docs/html/ext/lwg-active.html, docs/html/ext/lwg-defects.html:
Import from upstream, R22.
* include/bits/char_traits.h, include/bits/stl_iterator.h,
include/bits/stl_iterator_base_types.h, libsupc++/exception,
libsupc++/new, libsupc++/typeinfo: Use @brief markup.
* include/bits/deque.tcc, include/bits/stl_alloc.h,
include/bits/stl_deque.h, include/bits/stl_list.h: Postpone removal
of deprecated functions until 3.4. (Same timeframe, different text.)
* include/bits/stl_vector.h: Ditto. Also do the same cleanups that
the other sequence classes received.
Index: docs/html/23_containers/howto.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/23_containers/howto.html,v
retrieving revision 1.21
diff -u -3 -p -r1.21 howto.html
--- docs/html/23_containers/howto.html 8 Jul 2002 09:51:54 -0000 1.21
+++ docs/html/23_containers/howto.html 20 Jul 2002 06:17:22 -0000
@@ -27,7 +27,7 @@
<li><a href="#4">"Hinting" during insertion</a>
<li><a href="#5">Bitmasks and string arguments</a>
<li><a href="#6"><code>std::list::size()</code> is O(n)!</a>
- <li><a href="#7">Memory management for vectors</a>
+ <li><a href="#7">Space overhead management for vectors</a>
</ul>
<hr>
@@ -434,17 +434,19 @@
</p>
<hr>
-<h2><a name="7">Memory management for vectors</h2>
+<h2><a name="7">Space overhead management for vectors</h2>
<p>In
<a href="http://gcc.gnu.org/ml/libstdc++/2002-04/msg00105.html";>this
message to the list</a>, Daniel Kostecky announced work on an
alternate form of <code>std::vector</code> that would support hints
- about free store management. The design was also described, along
- with possible implementation choices.
+ on the number of elements to be over-allocated. The design was also
+ described, along with possible implementation choices.
</p>
- <p>The first alpha release was announced
- <a href="http://gcc.gnu.org/ml/libstdc++/2002-07/msg00048.html";>recently</a>
- and the releases themselves are available at
+ <p>The first two alpha releases were announced
+ <a href="http://gcc.gnu.org/ml/libstdc++/2002-07/msg00048.html";>here</a>
+ and
+ <a href="http://gcc.gnu.org/ml/libstdc++/2002-07/msg00111.html";>here</a>.
+ The releases themselves are available at
<a href="http://www.kotelna.sk/dk/sw/caphint/";>
http://www.kotelna.sk/dk/sw/caphint/</a>.
</p>
Index: include/bits/char_traits.h
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/include/bits/char_traits.h,v
retrieving revision 1.12
diff -u -3 -p -r1.12 char_traits.h
--- include/bits/char_traits.h 4 Jan 2002 21:27:31 -0000 1.12
+++ include/bits/char_traits.h 20 Jul 2002 06:17:24 -0000
@@ -46,9 +46,13 @@
namespace std
{
- /// 21.1.2 Basis for explicit _Traits specialization
- /// NB: That for any given actual character type this definition is
- /// probably wrong.
+ // 21.1.2
+ /**
+ * @brief Basis for explicit traits specializations.
+ *
+ * @note For any given actual character type, this definition is
+ * probably wrong.
+ */
template<class _CharT>
struct char_traits
{
Index: include/bits/deque.tcc
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/include/bits/deque.tcc,v
retrieving revision 1.1
diff -u -3 -p -r1.1 deque.tcc
--- include/bits/deque.tcc 12 Jun 2002 22:07:51 -0000 1.1
+++ include/bits/deque.tcc 20 Jul 2002 06:17:24 -0000
@@ -516,7 +516,7 @@ template <typename _Tp, typename _Alloc>
// Nothing seems to actually use this. According to the pattern followed by
// the rest of the SGI code, it would be called by the deprecated insert(pos)
// function, but that has been replaced. We'll take our time removing this
-// anyhow; mark for 3.3. -pme
+// anyhow; mark for 3.4. -pme
template <typename _Tp, typename _Alloc>
typename deque<_Tp,_Alloc>::iterator
deque<_Tp,_Alloc>::
Index: include/bits/stl_alloc.h
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/include/bits/stl_alloc.h,v
retrieving revision 1.22
diff -u -3 -p -r1.22 stl_alloc.h
--- include/bits/stl_alloc.h 27 Jun 2002 22:09:01 -0000 1.22
+++ include/bits/stl_alloc.h 20 Jul 2002 06:17:24 -0000
@@ -75,7 +75,7 @@
* @endif
*
* @note The @c reallocate member functions have been deprecated for 3.2
- * and will be removed in 3.3. You must define @c _GLIBCPP_DEPRECATED
+ * and will be removed in 3.4. You must define @c _GLIBCPP_DEPRECATED
* to make this visible in 3.2; see c++config.h.
*
* The canonical description of these classes is in docs/html/ext/howto.html
@@ -221,7 +221,8 @@ namespace std
/**
* @if maint
* This is used primarily (only?) in _Alloc_traits and other places to
- * help provide the _Alloc_type typedef.
+ * help provide the _Alloc_type typedef. All it does is forward the
+ * requests after some minimal checking.
*
* This is neither "standard"-conforming nor "SGI". The _Alloc parameter
* must be "SGI" style.
@@ -620,8 +621,10 @@ namespace std
/**
- * This is a "standard" allocator, as per [20.4]. The private _Alloc is
- * "SGI" style. (See comments at the top of stl_alloc.h.)
+ * @brief The "standard" allocator, as per [20.4].
+ *
+ * The private _Alloc is "SGI" style. (See comments at the top
+ * of stl_alloc.h.)
*
* The underlying allocator behaves as follows.
* - if __USE_MALLOC then
Index: include/bits/stl_deque.h
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/include/bits/stl_deque.h,v
retrieving revision 1.25
diff -u -3 -p -r1.25 stl_deque.h
--- include/bits/stl_deque.h 11 Jul 2002 04:43:15 -0000 1.25
+++ include/bits/stl_deque.h 20 Jul 2002 06:17:24 -0000
@@ -1034,7 +1034,7 @@ public:
* of a %deque this operation can be done in constant time. You should
* consider using push_front(value_type()) instead.
*
- * @note This was deprecated in 3.2 and will be removed in 3.3. You must
+ * @note This was deprecated in 3.2 and will be removed in 3.4. You must
* define @c _GLIBCPP_DEPRECATED to make this visible in 3.2; see
* c++config.h.
*/
@@ -1078,7 +1078,7 @@ public:
* of a %deque this operation can be done in constant time. You should
* consider using push_back(value_type()) instead.
*
- * @note This was deprecated in 3.2 and will be removed in 3.3. You must
+ * @note This was deprecated in 3.2 and will be removed in 3.4. You must
* define @c _GLIBCPP_DEPRECATED to make this visible in 3.2; see
* c++config.h.
*/
@@ -1154,7 +1154,7 @@ public:
* specified location. You should consider using
* insert(position,value_type()) instead.
*
- * @note This was deprecated in 3.2 and will be removed in 3.3. You must
+ * @note This was deprecated in 3.2 and will be removed in 3.4. You must
* define @c _GLIBCPP_DEPRECATED to make this visible in 3.2; see
* c++config.h.
*/
Index: include/bits/stl_iterator.h
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/include/bits/stl_iterator.h,v
retrieving revision 1.21
diff -u -3 -p -r1.21 stl_iterator.h
--- include/bits/stl_iterator.h 2 Jul 2002 18:42:57 -0000 1.21
+++ include/bits/stl_iterator.h 20 Jul 2002 06:17:24 -0000
@@ -317,6 +317,8 @@ namespace std
// 24.4.2.2.1 back_insert_iterator
/**
+ * @brief Turns assignment into insertion.
+ *
* These are output iterators, constructed from a container-of-T.
* Assigning a T to the iterator appends it to the container using
* push_back.
@@ -387,6 +389,8 @@ namespace std
{ return back_insert_iterator<_Container>(__x); }
/**
+ * @brief Turns assignment into insertion.
+ *
* These are output iterators, constructed from a container-of-T.
* Assigning a T to the iterator prepends it to the container using
* push_front.
@@ -456,6 +460,8 @@ namespace std
{ return front_insert_iterator<_Container>(__x); }
/**
+ * @brief Turns assignment into insertion.
+ *
* These are output iterators, constructed from a container-of-T.
* Assigning a T to the iterator inserts it in the container at the
* %iterator's position, rather than overwriting the value at that
Index: include/bits/stl_iterator_base_types.h
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/include/bits/stl_iterator_base_types.h,v
retrieving revision 1.11
diff -u -3 -p -r1.11 stl_iterator_base_types.h
--- include/bits/stl_iterator_base_types.h 27 Mar 2002 21:41:33 -0000 1.11
+++ include/bits/stl_iterator_base_types.h 20 Jul 2002 06:17:24 -0000
@@ -68,13 +68,12 @@
namespace std
{
- /**
+ /** @{
* @defgroup iterator_tags Iterator Tags
* These are empty types, used to distinguish different iterators. The
* distinction is not made by what they contain, but simply by what they
* are. Different underlying algorithms can then be used based on the
* different operations supporetd by different iterator types.
- * @{
*/
/// Marking input iterators.
struct input_iterator_tag {};
@@ -90,6 +89,8 @@ namespace std
/**
+ * @brief Common %iterator class.
+ *
* This class does nothing but define nested typedefs. %Iterator classes
* can inherit from this class to save some work. The typedefs are then
* used in specializations and overloading.
@@ -98,8 +99,9 @@ namespace std
* such as @c operator++ and the like. (How could there be?)
*/
template<typename _Category, typename _Tp, typename _Distance = ptrdiff_t,
- typename _Pointer = _Tp*, typename _Reference = _Tp&>
- struct iterator {
+ typename _Pointer = _Tp*, typename _Reference = _Tp&>
+ struct iterator
+ {
/// One of the @link iterator_tags tag types@endlink.
typedef _Category iterator_category;
/// The type "pointed to" by the iterator.
Index: include/bits/stl_list.h
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/include/bits/stl_list.h,v
retrieving revision 1.16
diff -u -3 -p -r1.16 stl_list.h
--- include/bits/stl_list.h 11 Jul 2002 04:43:15 -0000 1.16
+++ include/bits/stl_list.h 20 Jul 2002 06:17:24 -0000
@@ -715,7 +715,7 @@ public:
* of a %list this operation can be done in constant time. You should
* consider using push_front(value_type()) instead.
*
- * @note This was deprecated in 3.2 and will be removed in 3.3. You must
+ * @note This was deprecated in 3.2 and will be removed in 3.4. You must
* define @c _GLIBCPP_DEPRECATED to make this visible in 3.2; see
* c++config.h.
*/
@@ -758,7 +758,7 @@ public:
* of a %list this operation can be done in constant time. You should
* consider using push_back(value_type()) instead.
*
- * @note This was deprecated in 3.2 and will be removed in 3.3. You must
+ * @note This was deprecated in 3.2 and will be removed in 3.4. You must
* define @c _GLIBCPP_DEPRECATED to make this visible in 3.2; see
* c++config.h.
*/
@@ -810,7 +810,7 @@ public:
* Due to the nature of a %list this operation can be done in constant
* time, and does not invalidate iterators and references.
*
- * @note This was deprecated in 3.2 and will be removed in 3.3. You must
+ * @note This was deprecated in 3.2 and will be removed in 3.4. You must
* define @c _GLIBCPP_DEPRECATED to make this visible in 3.2; see
* c++config.h.
*/
Index: include/bits/stl_vector.h
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/include/bits/stl_vector.h,v
retrieving revision 1.25
diff -u -3 -p -r1.25 stl_vector.h
--- include/bits/stl_vector.h 11 Jul 2002 04:43:15 -0000 1.25
+++ include/bits/stl_vector.h 20 Jul 2002 06:17:24 -0000
@@ -253,7 +253,7 @@ public:
explicit
vector(size_type __n)
: _Base(__n, allocator_type())
- { _M_finish = uninitialized_fill_n(_M_start, __n, _Tp()); }
+ { _M_finish = uninitialized_fill_n(_M_start, __n, value_type()); }
/**
* @brief %Vector copy constructor.
@@ -489,7 +489,6 @@ public:
*/
reference
operator[](size_type __n) { return *(begin() + __n); }
- // XXX do we need to convert to normal_iterator first?
/**
* @brief Subscript access to the data contained in the %vector.
@@ -545,7 +544,6 @@ public:
*/
reference
front() { return *begin(); }
- // XXX do we need to convert to normal_iterator first?
/**
* Returns a read-only (constant) reference to the data at the first
@@ -631,7 +629,7 @@ public:
* Note that this kind of operation could be expensive for a vector and if
* it is frequently used the user should consider using std::list.
*
- * @note This was deprecated in 3.2 and will be removed in 3.3. You must
+ * @note This was deprecated in 3.2 and will be removed in 3.4. You must
* define @c _GLIBCPP_DEPRECATED to make this visible in 3.2; see
* c++config.h.
*/
@@ -914,7 +912,7 @@ protected:
*/
template <typename _Tp, typename _Alloc>
inline bool
- operator==(const vector<_Tp, _Alloc>& __x, const vector<_Tp, _Alloc>& __y)
+ operator==(const vector<_Tp,_Alloc>& __x, const vector<_Tp,_Alloc>& __y)
{
return __x.size() == __y.size() &&
equal(__x.begin(), __x.end(), __y.begin());
@@ -933,7 +931,7 @@ template <typename _Tp, typename _Alloc>
*/
template <typename _Tp, typename _Alloc>
inline bool
- operator<(const vector<_Tp, _Alloc>& __x, const vector<_Tp, _Alloc>& __y)
+ operator<(const vector<_Tp,_Alloc>& __x, const vector<_Tp,_Alloc>& __y)
{
return lexicographical_compare(__x.begin(), __x.end(),
__y.begin(), __y.end());
@@ -941,40 +939,34 @@ template <typename _Tp, typename _Alloc>
/// Based on operator==
template <typename _Tp, typename _Alloc>
-inline bool
-operator!=(const vector<_Tp, _Alloc>& __x, const vector<_Tp, _Alloc>& __y) {
- return !(__x == __y);
-}
+ inline bool
+ operator!=(const vector<_Tp,_Alloc>& __x, const vector<_Tp,_Alloc>& __y)
+ { return !(__x == __y); }
/// Based on operator<
template <typename _Tp, typename _Alloc>
-inline bool
-operator>(const vector<_Tp, _Alloc>& __x, const vector<_Tp, _Alloc>& __y) {
- return __y < __x;
-}
+ inline bool
+ operator>(const vector<_Tp,_Alloc>& __x, const vector<_Tp,_Alloc>& __y)
+ { return __y < __x; }
/// Based on operator<
template <typename _Tp, typename _Alloc>
-inline bool
-operator<=(const vector<_Tp, _Alloc>& __x, const vector<_Tp, _Alloc>& __y) {
- return !(__y < __x);
-}
+ inline bool
+ operator<=(const vector<_Tp,_Alloc>& __x, const vector<_Tp,_Alloc>& __y)
+ { return !(__y < __x); }
/// Based on operator<
template <typename _Tp, typename _Alloc>
-inline bool
-operator>=(const vector<_Tp, _Alloc>& __x, const vector<_Tp, _Alloc>& __y) {
- return !(__x < __y);
-}
+ inline bool
+ operator>=(const vector<_Tp,_Alloc>& __x, const vector<_Tp,_Alloc>& __y)
+ { return !(__x < __y); }
/// See std::vector::swap().
template <typename _Tp, typename _Alloc>
-inline void swap(vector<_Tp, _Alloc>& __x, vector<_Tp, _Alloc>& __y)
-{
- __x.swap(__y);
-}
+ inline void
+ swap(vector<_Tp,_Alloc>& __x, vector<_Tp,_Alloc>& __y)
+ { __x.swap(__y); }
} // namespace std
#endif /* __GLIBCPP_INTERNAL_VECTOR_H */
-
Index: libsupc++/exception
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/libsupc++/exception,v
retrieving revision 1.13
diff -u -3 -p -r1.13 exception
--- libsupc++/exception 2 Apr 2002 02:07:18 -0000 1.13
+++ libsupc++/exception 20 Jul 2002 06:17:24 -0000
@@ -41,11 +41,13 @@ extern "C++" {
namespace std
{
- /** This is the base class for all exceptions thrown by the standard
+ /**
+ * @brief Base class for all library exceptions.
+ *
+ * This is the base class for all exceptions thrown by the standard
* library, and by certain language expressions. You are free to derive
* your own %exception classes, or use a different hierarchy, or to
* throw non-class data (e.g., fundamental types).
- * @brief Base class for all library exceptions.
*/
class exception
{
Index: libsupc++/new
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/libsupc++/new,v
retrieving revision 1.11
diff -u -3 -p -r1.11 new
--- libsupc++/new 16 Jul 2002 08:28:40 -0000 1.11
+++ libsupc++/new 20 Jul 2002 06:17:24 -0000
@@ -45,7 +45,10 @@ extern "C++" {
namespace std
{
- /** @c bad_alloc (or classes derived from it) is used to report allocation
+ /**
+ * @brief Exception possibly thrown by @c new.
+ *
+ * @c bad_alloc (or classes derived from it) is used to report allocation
* errors from the throwing forms of @c new. */
class bad_alloc : public exception
{
Index: libsupc++/typeinfo
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/libsupc++/typeinfo,v
retrieving revision 1.13
diff -u -3 -p -r1.13 typeinfo
--- libsupc++/typeinfo 16 Apr 2002 00:45:30 -0000 1.13
+++ libsupc++/typeinfo 20 Jul 2002 06:17:24 -0000
@@ -54,9 +54,12 @@ namespace __cxxabiv1
namespace std
{
- /** The @c type_info class describes type information generated by
+ /**
+ * @brief Part of RTTI.
+ *
+ * The @c type_info class describes type information generated by
* an implementation.
- * @brief Used in RTTI. */
+ */
class type_info
{
public:
@@ -124,7 +127,10 @@ namespace std
void **__obj_ptr) const;
};
- /** If you attempt an invalid @c dynamic_cast expression, an instance of
+ /**
+ * @brief Thrown during incorrect typecasting.
+ *
+ * If you attempt an invalid @c dynamic_cast expression, an instance of
* this class (or something derived from this class) is thrown. */
class bad_cast : public exception
{