On 02/05/19 16:47 +0100, Jonathan Wakely wrote:
I've just committed a series of patches to improve the organization
and formatting of the Doxygen-generated API documentation.
- Update libstdc++ Doxygen config
- Adjust Doxygen processing of pb_ds containers
- Fix markup for Parallel Mode docs
- Improve Doxygen docs for nested namespaces
- Improve API docs for mathematical special functions
- Improve API docs for <memory> and <scoped_allocator>
- Improve docs for Filesystem TS
- Improve docs for Library Fundamentals TS
- Improve docs for Networking TS
- Improve docs for C++17 Filesystem library
- Improve docs for mutexes
- Allow Markdown formatting in Doxygen comments
- Miscellaneous API doc improvements
The patch is large so I've bzipped it, but it's almost entirely
changes to comments, with a couple of small re-arrangements of code to
improve the generated HTML docs.
Committed to trunk.
More changes coming soon too (including enabling Doxygen processing
for the C++17 components).
Another similar patch for smart pointers.
Tested x86_64-linux. Committed to trunk.
commit e483bf175e8d3bb0db26428979e5cbc22de3731e
Author: Jonathan Wakely <jwak...@redhat.com>
Date: Thu May 2 17:25:59 2019 +0100
Improve smart pointer docs
* include/bits/shared_ptr.h: Improve docs.
* include/bits/shared_ptr_atomic.h: Likewise.
* include/bits/unique_ptr.h: Likewise. Adjust whitespace.
diff --git a/libstdc++-v3/include/bits/shared_ptr.h b/libstdc++-v3/include/bits/shared_ptr.h
index 2d53478f1f4..a38c1988973 100644
--- a/libstdc++-v3/include/bits/shared_ptr.h
+++ b/libstdc++-v3/include/bits/shared_ptr.h
@@ -82,6 +82,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
}
/// 20.7.2.2.10 shared_ptr get_deleter
+ /// @relates shared_ptr
template<typename _Del, typename _Tp>
inline _Del*
get_deleter(const shared_ptr<_Tp>& __p) noexcept
@@ -96,8 +97,15 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
/**
* @brief A smart pointer with reference-counted copy semantics.
*
- * The object pointed to is deleted when the last shared_ptr pointing to
- * it is destroyed or reset.
+ * A `shared_ptr` object is either empty or _owns_ a pointer passed
+ * to the constructor. Copies of a `shared_ptr` share ownership of
+ * the same pointer. When the last `shared_ptr` that owns the pointer
+ * is destroyed or reset, the owned pointer is freed (either by `delete`
+ * or by invoking a custom deleter that was passed to the constructor).
+ *
+ * A `shared_ptr` also stores another pointer, which is usually
+ * (but not always) the same pointer as it owns. The stored pointer
+ * can be retrieved by calling the `get()` member function.
*/
template<typename _Tp>
class shared_ptr : public __shared_ptr<_Tp>
@@ -370,6 +378,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
friend class weak_ptr<_Tp>;
};
+ /// @relates shared_ptr @{
+
#if __cpp_deduction_guides >= 201606
template<typename _Tp>
shared_ptr(weak_ptr<_Tp>) -> shared_ptr<_Tp>;
@@ -480,12 +490,14 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
{ return !(nullptr < __a); }
// 20.7.2.2.8 shared_ptr specialized algorithms.
+ /// Swap overload for shared_ptr
template<typename _Tp>
inline void
swap(shared_ptr<_Tp>& __a, shared_ptr<_Tp>& __b) noexcept
{ __a.swap(__b); }
// 20.7.2.2.9 shared_ptr casts.
+ /// Convert type of `shared_ptr`, via `static_cast`
template<typename _Tp, typename _Up>
inline shared_ptr<_Tp>
static_pointer_cast(const shared_ptr<_Up>& __r) noexcept
@@ -494,6 +506,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
return _Sp(__r, static_cast<typename _Sp::element_type*>(__r.get()));
}
+ /// Convert type of `shared_ptr`, via `const_cast`
template<typename _Tp, typename _Up>
inline shared_ptr<_Tp>
const_pointer_cast(const shared_ptr<_Up>& __r) noexcept
@@ -502,6 +515,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
return _Sp(__r, const_cast<typename _Sp::element_type*>(__r.get()));
}
+ /// Convert type of `shared_ptr`, via `dynamic_cast`
template<typename _Tp, typename _Up>
inline shared_ptr<_Tp>
dynamic_pointer_cast(const shared_ptr<_Up>& __r) noexcept
@@ -512,7 +526,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
return _Sp();
}
-#if __cplusplus > 201402L
+#if __cplusplus >= 201703L
+ /// Convert type of `shared_ptr`, via `reinterpret_cast`
template<typename _Tp, typename _Up>
inline shared_ptr<_Tp>
reinterpret_pointer_cast(const shared_ptr<_Up>& __r) noexcept
@@ -522,6 +537,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
}
#endif
+ // @}
+
/**
* @brief A smart pointer with weak semantics.
*
@@ -601,6 +618,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
#endif
// 20.7.2.3.6 weak_ptr specialized algorithms.
+ /// Swap overload for weak_ptr
+ /// @relates weak_ptr
template<typename _Tp>
inline void
swap(weak_ptr<_Tp>& __a, weak_ptr<_Tp>& __b) noexcept
@@ -617,12 +636,14 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
{ };
/// Partial specialization of owner_less for shared_ptr.
+ /// @relates shared_ptr
template<typename _Tp>
struct owner_less<shared_ptr<_Tp>>
: public _Sp_owner_less<shared_ptr<_Tp>, weak_ptr<_Tp>>
{ };
/// Partial specialization of owner_less for weak_ptr.
+ /// @relates weak_ptr
template<typename _Tp>
struct owner_less<weak_ptr<_Tp>>
: public _Sp_owner_less<weak_ptr<_Tp>, shared_ptr<_Tp>>
@@ -683,6 +704,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
mutable weak_ptr<_Tp> _M_weak_this;
};
+ /// @relates unique_ptr @{
+
/**
* @brief Create an object that is owned by a shared_ptr.
* @param __a An allocator.
@@ -730,6 +753,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
}
};
+ // @} relates shared_ptr
// @} group pointer_abstractions
#if __cplusplus >= 201703L
diff --git a/libstdc++-v3/include/bits/shared_ptr_atomic.h b/libstdc++-v3/include/bits/shared_ptr_atomic.h
index fb99eb55b14..93c575a79f2 100644
--- a/libstdc++-v3/include/bits/shared_ptr_atomic.h
+++ b/libstdc++-v3/include/bits/shared_ptr_atomic.h
@@ -40,6 +40,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
* @addtogroup pointer_abstractions
* @{
*/
+ /// @relates shared_ptr @{
+
+ /// @cond undocumented
struct _Sp_locker
{
@@ -60,6 +63,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
#endif
};
+ /// @endcond
+
/**
* @brief Report whether shared_ptr atomic operations are lock-free.
* @param __p A non-null pointer to a shared_ptr object.
@@ -322,6 +327,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
}
// @}
+ // @} relates shared_ptr
// @} group pointer_abstractions
_GLIBCXX_END_NAMESPACE_VERSION
diff --git a/libstdc++-v3/include/bits/unique_ptr.h b/libstdc++-v3/include/bits/unique_ptr.h
index 963e4eb7d44..549db875783 100644
--- a/libstdc++-v3/include/bits/unique_ptr.h
+++ b/libstdc++-v3/include/bits/unique_ptr.h
@@ -686,6 +686,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
unique_ptr& operator=(const unique_ptr&) = delete;
};
+ /// @relates unique_ptr @{
+
template<typename _Tp, typename _Dp>
inline
#if __cplusplus > 201402L || !defined(__STRICT_ANSI__) // c++1z or gnu++11
@@ -754,14 +756,18 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
template<typename _Tp, typename _Dp>
_GLIBCXX_NODISCARD inline bool
operator<(const unique_ptr<_Tp, _Dp>& __x, nullptr_t)
- { return std::less<typename unique_ptr<_Tp, _Dp>::pointer>()(__x.get(),
- nullptr); }
+ {
+ return std::less<typename unique_ptr<_Tp, _Dp>::pointer>()(__x.get(),
+ nullptr);
+ }
template<typename _Tp, typename _Dp>
_GLIBCXX_NODISCARD inline bool
operator<(nullptr_t, const unique_ptr<_Tp, _Dp>& __x)
- { return std::less<typename unique_ptr<_Tp, _Dp>::pointer>()(nullptr,
- __x.get()); }
+ {
+ return std::less<typename unique_ptr<_Tp, _Dp>::pointer>()(nullptr,
+ __x.get());
+ }
template<typename _Tp, typename _Dp,
typename _Up, typename _Ep>
@@ -790,14 +796,18 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
template<typename _Tp, typename _Dp>
_GLIBCXX_NODISCARD inline bool
operator>(const unique_ptr<_Tp, _Dp>& __x, nullptr_t)
- { return std::less<typename unique_ptr<_Tp, _Dp>::pointer>()(nullptr,
- __x.get()); }
+ {
+ return std::less<typename unique_ptr<_Tp, _Dp>::pointer>()(nullptr,
+ __x.get());
+ }
template<typename _Tp, typename _Dp>
_GLIBCXX_NODISCARD inline bool
operator>(nullptr_t, const unique_ptr<_Tp, _Dp>& __x)
- { return std::less<typename unique_ptr<_Tp, _Dp>::pointer>()(__x.get(),
- nullptr); }
+ {
+ return std::less<typename unique_ptr<_Tp, _Dp>::pointer>()(__x.get(),
+ nullptr);
+ }
template<typename _Tp, typename _Dp,
typename _Up, typename _Ep>
@@ -834,6 +844,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
#define __cpp_lib_make_unique 201304
+ /// @cond undocumented
+
template<typename _Tp>
struct _MakeUniq
{ typedef unique_ptr<_Tp> __single_object; };
@@ -846,6 +858,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
struct _MakeUniq<_Tp[_Bound]>
{ struct __invalid_type { }; };
+ /// @endcond
+
/// std::make_unique for single objects
template<typename _Tp, typename... _Args>
inline typename _MakeUniq<_Tp>::__single_object
@@ -864,6 +878,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
make_unique(_Args&&...) = delete;
#endif
+ // @} relates unique_ptr
// @} group pointer_abstractions
#if __cplusplus >= 201703L
