This is the mail archive of the libstdc++@gcc.gnu.org mailing list for the libstdc++ project.

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: [PATCH] Several patches to improve libstdc++ API docs

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 <jwakely@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
Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]