public inbox for libstdc++@gcc.gnu.org
 help / color / mirror / Atom feed
* [committed] libstdc++: Improvements to Doxygen markup
@ 2021-07-01 18:25 Jonathan Wakely
  0 siblings, 0 replies; only message in thread
From: Jonathan Wakely @ 2021-07-01 18:25 UTC (permalink / raw)
  To: libstdc++, gcc-patches

[-- Attachment #1: Type: text/plain, Size: 1662 bytes --]

This attempst to improve the doxygen output to work around what seems to
be some bugs in doxygen (issues 8635 and 8638).

The @addtogroup command doesn't work for entities inside a nested
namespace (see 8635) so we need to close and reopen groups on entering
and leaving nested namespaces. This fixes the problem that
chrono::duration and chrono::time_point were not documented in the
"Time" documentation group. I am unable to make the path classes appear
as part of their relevant groups (File System and Filesystem TS), nor
the contents of <exception> or <system_error>. I have made some minor
improvements to the docs for those types, including starting to address
PR 97001 by adding @since to the doxygen comments.

This change also excludes the <experimental/bits/net.h> header from
Doxygen processing, so we don't get an unwanted "Networking-ts" group
in the documentation.

Signed-off-by: Jonathan Wakely <jwakely@redhat.com>

libstdc++-v3/ChangeLog:

	* doc/doxygen/doxygroups.cc: Fix docs for std::literals.
	* doc/doxygen/user.cfg.in: Exclude the Networking TS header.
	Add some more predefined macros.
	* include/bits/fs_fwd.h: Move @addtogroup commands inside
	namespaces. Add better documentation.
	* include/bits/fs_path.h: Likewise.
	* include/experimental/bits/fs_fwd.h: Likewise.
	* include/experimental/bits/fs_path.h: Likewise.
	* include/ext/throw_allocator.h: Fix typo and improve docs.
	* include/std/chrono: Move @addtogroup commands.
	* include/std/system_error: Move @addtogroup commands.
	* libsupc++/exception: Improve documentation.
	* libsupc++/exception.h: Add @since documentation.

Tested powerpc64le-linux. Committed to trunk.


[-- Attachment #2: patch.txt --]
[-- Type: text/plain, Size: 27424 bytes --]

commit f2ce64b53fa76a4c192fe51b2f6c5a863a3b1241
Author: Jonathan Wakely <jwakely@redhat.com>
Date:   Thu Jul 1 00:30:54 2021

    libstdc++: Improvements to Doxygen markup
    
    This attempst to improve the doxygen output to work around what seems to
    be some bugs in doxygen (issues 8635 and 8638).
    
    The @addtogroup command doesn't work for entities inside a nested
    namespace (see 8635) so we need to close and reopen groups on entering
    and elaving nested namespaces. This fixes the problem that
    chrono::duration and chrono::time_point were not documented in the
    "Time" documentation group. I am unable to make the path classes appear
    as part of their relevant groups (File System and Filesystem TS), nor
    the contents of <exception> or <system_error>. I have made some minor
    improvements to the docs for those types, including starting to address
    PR 97001 by adding @since to the doxygen comments.
    
    This change also excludes the <experimental/bits/net.h> header from
    Doxygen processing, so we don't get an unwanted "Networking-ts" group
    in the documentation.
    
    Signed-off-by: Jonathan Wakely <jwakely@redhat.com>
    
    libstdc++-v3/ChangeLog:
    
            * doc/doxygen/doxygroups.cc: Fix docs for std::literals.
            * doc/doxygen/user.cfg.in: Exclude the Networking TS header.
            Add some more predefined macros.
            * include/bits/fs_fwd.h: Move @addtogroup commands inside
            namespaces. Add better documentation.
            * include/bits/fs_path.h: Likewise.
            * include/experimental/bits/fs_fwd.h: Likewise.
            * include/experimental/bits/fs_path.h: Likewise.
            * include/ext/throw_allocator.h: Fix typo and improve docs.
            * include/std/chrono: Move @addtogroup commands.
            * include/std/system_error: Move @addtogroup commands.
            * libsupc++/exception: Improve documentation.
            * libsupc++/exception.h: Add @since documentation.

diff --git a/libstdc++-v3/doc/doxygen/doxygroups.cc b/libstdc++-v3/doc/doxygen/doxygroups.cc
index 506cb145b35..42f7d447520 100644
--- a/libstdc++-v3/doc/doxygen/doxygroups.cc
+++ b/libstdc++-v3/doc/doxygen/doxygroups.cc
@@ -19,7 +19,7 @@
 /** @namespace std
  *  @brief ISO C++ entities toplevel namespace is std.
 */
-/** @namespace std
+/** @namespace std::literals
  *  @brief ISO C++ inline namespace for literal suffixes.
 */
 /** @namespace std::__detail
@@ -43,7 +43,7 @@
  *  @ingroup extensions
 */
 /** @namespace __gnu_cxx::__detail
- *  @brief Implementation details not part of the namespace __gnu_cxx 
+ *  @brief Implementation details not part of the namespace __gnu_cxx
  *  interface.
 */
 /** @namespace __gnu_internal
diff --git a/libstdc++-v3/doc/doxygen/user.cfg.in b/libstdc++-v3/doc/doxygen/user.cfg.in
index 3510c736789..349b9ec9c36 100644
--- a/libstdc++-v3/doc/doxygen/user.cfg.in
+++ b/libstdc++-v3/doc/doxygen/user.cfg.in
@@ -1092,7 +1092,8 @@ RECURSIVE              = NO
 # Note that relative paths are relative to the directory from which doxygen is
 # run.
 
-EXCLUDE                = Makefile
+EXCLUDE                = Makefile \
+                         include/experimental/bits/net.h
 
 # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
 # directories that are symbolic links (a Unix file system feature) are excluded
@@ -2446,7 +2447,9 @@ PREDEFINED             = __cplusplus=201703L \
                          "_GLIBCXX17_DEPRECATED_SUGGEST(E)= " \
                          "_GLIBCXX20_DEPRECATED(E)= " \
                          "_GLIBCXX20_DEPRECATED(E)= " \
-                         _GLIBCXX17_INLINE=inline
+                         _GLIBCXX17_INLINE=inline \
+			 _GLIBCXX_CHRONO_INT64_T=int64_t \
+			 _GLIBCXX_DEFAULT_ABI_TAG
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
 # tag can be used to specify a list of macro names that should be expanded. The
diff --git a/libstdc++-v3/include/bits/fs_fwd.h b/libstdc++-v3/include/bits/fs_fwd.h
index 3a1ff35f8e2..a7f5a37709c 100644
--- a/libstdc++-v3/include/bits/fs_fwd.h
+++ b/libstdc++-v3/include/bits/fs_fwd.h
@@ -40,17 +40,18 @@ namespace std _GLIBCXX_VISIBILITY(default)
 {
 _GLIBCXX_BEGIN_NAMESPACE_VERSION
 
-/** @addtogroup filesystem
- *  @{
- */
-
 /// ISO C++ 2017 namespace for File System library
 namespace filesystem
 {
 #if _GLIBCXX_USE_CXX11_ABI
+/// @cond undocumented
 inline namespace __cxx11 __attribute__((__abi_tag__ ("cxx11"))) { }
+/// @endcond
 #endif
 
+/** @addtogroup filesystem
+ *  @{
+ */
 
   class file_status;
 _GLIBCXX_BEGIN_NAMESPACE_CXX11
@@ -61,6 +62,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
   class recursive_directory_iterator;
 _GLIBCXX_END_NAMESPACE_CXX11
 
+  /// Information about free space on a disk
   struct space_info
   {
     uintmax_t capacity;
@@ -72,12 +74,13 @@ _GLIBCXX_END_NAMESPACE_CXX11
 #endif
   };
 
+  /// Enumerated type representing the type of a file
   enum class file_type : signed char {
       none = 0, not_found = -1, regular = 1, directory = 2, symlink = 3,
       block = 4, character = 5, fifo = 6, socket = 7, unknown = 8
   };
 
-  /// Bitmask type
+  /// Bitmask type controlling effects of `filesystem::copy`
   enum class copy_options : unsigned short {
       none = 0,
       skip_existing = 1, overwrite_existing = 2, update_existing = 4,
@@ -86,6 +89,8 @@ _GLIBCXX_END_NAMESPACE_CXX11
       directories_only = 64, create_symlinks = 128, create_hard_links = 256
   };
 
+  /// @{
+  /// @relates copy_options
   constexpr copy_options
   operator&(copy_options __x, copy_options __y) noexcept
   {
@@ -128,9 +133,10 @@ _GLIBCXX_END_NAMESPACE_CXX11
   inline copy_options&
   operator^=(copy_options& __x, copy_options __y) noexcept
   { return __x = __x ^ __y; }
+  /// @}
 
 
-  /// Bitmask type
+  /// Bitmask type representing file access permissions
   enum class perms : unsigned {
       none		=  0,
       owner_read	=  0400,
@@ -153,6 +159,8 @@ _GLIBCXX_END_NAMESPACE_CXX11
       unknown		=  0xFFFF,
   };
 
+  /// @{
+  /// @relates perm_options
   constexpr perms
   operator&(perms __x, perms __y) noexcept
   {
@@ -195,8 +203,9 @@ _GLIBCXX_END_NAMESPACE_CXX11
   inline perms&
   operator^=(perms& __x, perms __y) noexcept
   { return __x = __x ^ __y; }
+  /// @}
 
-  /// Bitmask type
+  /// Bitmask type controlling changes to permissions
   enum class perm_options : unsigned {
       replace	= 0x1,
       add	= 0x2,
@@ -204,6 +213,8 @@ _GLIBCXX_END_NAMESPACE_CXX11
       nofollow	= 0x8
   };
 
+  /// @{
+  /// @relates perm_options
   constexpr perm_options
   operator&(perm_options __x, perm_options __y) noexcept
   {
@@ -246,12 +257,15 @@ _GLIBCXX_END_NAMESPACE_CXX11
   inline perm_options&
   operator^=(perm_options& __x, perm_options __y) noexcept
   { return __x = __x ^ __y; }
+  /// @}
 
-  // Bitmask type
+  /// Bitmask type controlling directory iteration
   enum class directory_options : unsigned char {
       none = 0, follow_directory_symlink = 1, skip_permission_denied = 2
   };
 
+  /// @{
+  /// @relates directory_options
   constexpr directory_options
   operator&(directory_options __x, directory_options __y) noexcept
   {
@@ -294,7 +308,9 @@ _GLIBCXX_END_NAMESPACE_CXX11
   inline directory_options&
   operator^=(directory_options& __x, directory_options __y) noexcept
   { return __x = __x ^ __y; }
+  /// @}
 
+  /// The type used for file timestamps
   using file_time_type = __file_clock::time_point;
 
   // operational functions
@@ -338,8 +354,8 @@ _GLIBCXX_END_NAMESPACE_CXX11
   bool is_regular_file(file_status) noexcept;
   bool is_symlink(file_status) noexcept;
 
-} // namespace filesystem
 /// @}
+} // namespace filesystem
 _GLIBCXX_END_NAMESPACE_VERSION
 } // namespace std
 #endif // C++17
diff --git a/libstdc++-v3/include/bits/fs_path.h b/libstdc++-v3/include/bits/fs_path.h
index 5e285204527..4fcd1def92f 100644
--- a/libstdc++-v3/include/bits/fs_path.h
+++ b/libstdc++-v3/include/bits/fs_path.h
@@ -63,15 +63,13 @@ namespace filesystem
 {
 _GLIBCXX_BEGIN_NAMESPACE_CXX11
 
-  /** @addtogroup filesystem
-   *  @{
-   */
-
   class path;
 
   /// @cond undocumented
 namespace __detail
 {
+  /// @addtogroup filesystem
+  /// @{
   template<typename _CharT>
     inline constexpr bool __is_encoded_char = false;
   template<>
@@ -238,10 +236,15 @@ namespace __detail
 	return basic_string<_EcharT>(__first, __last);
     }
 
+  /// @} group filesystem
 } // namespace __detail
   /// @endcond
 
-  /// A filesystem path.
+  /// @addtogroup filesystem
+  /// @{
+
+  /// A filesystem path
+  /// @ingroup filesystem
   class path
   {
   public:
@@ -693,7 +696,8 @@ namespace __detail
     struct _Parser;
   };
 
-  /// @relates std::filesystem::path @{
+  /// @{
+  /// @relates std::filesystem::path
 
   inline void swap(path& __lhs, path& __rhs) noexcept { __lhs.swap(__rhs); }
 
@@ -1347,6 +1351,8 @@ namespace __detail
 _GLIBCXX_END_NAMESPACE_CXX11
 } // namespace filesystem
 
+/// @cond undocumented
+
 inline ptrdiff_t
 distance(filesystem::path::iterator __first, filesystem::path::iterator __last)
 { return __path_iter_distance(__first, __last); }
@@ -1358,6 +1364,8 @@ template<typename _InputIterator, typename _Distance>
 
 extern template class __shared_ptr<const filesystem::filesystem_error::_Impl>;
 
+/// @endcond
+
 _GLIBCXX_END_NAMESPACE_VERSION
 } // namespace std
 
diff --git a/libstdc++-v3/include/experimental/bits/fs_fwd.h b/libstdc++-v3/include/experimental/bits/fs_fwd.h
index 2b0655d2a69..8d63e095be5 100644
--- a/libstdc++-v3/include/experimental/bits/fs_fwd.h
+++ b/libstdc++-v3/include/experimental/bits/fs_fwd.h
@@ -60,6 +60,11 @@ inline namespace __cxx11 __attribute__((__abi_tag__ ("cxx11"))) { }
    * such as paths, regular files, and directories.
    *
    * ISO/IEC TS 18822:2015	C++ File System Technical Specification
+   *
+   * @since C++11
+   *
+   * @remark Link using `-lstdc++fs` to use these types and functions.
+   *
    * @{
    */
 
@@ -72,6 +77,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
   class recursive_directory_iterator;
 _GLIBCXX_END_NAMESPACE_CXX11
 
+  /// Information about free space on a disk
   struct space_info
   {
     uintmax_t capacity;
@@ -79,12 +85,13 @@ _GLIBCXX_END_NAMESPACE_CXX11
     uintmax_t available;
   };
 
+  /// Enumerated type representing the type of a file
   enum class file_type : signed char {
       none = 0, not_found = -1, regular = 1, directory = 2, symlink = 3,
       block = 4, character = 5, fifo = 6, socket = 7, unknown = 8
   };
 
-  /// Bitmask type
+  /// Bitmask type controlling effects of `filesystem::copy`
   enum class copy_options : unsigned short {
       none = 0,
       skip_existing = 1, overwrite_existing = 2, update_existing = 4,
@@ -93,6 +100,8 @@ _GLIBCXX_END_NAMESPACE_CXX11
       directories_only = 64, create_symlinks = 128, create_hard_links = 256
   };
 
+  /// @{
+  /// @relates copy_options
   constexpr copy_options
   operator&(copy_options __x, copy_options __y) noexcept
   {
@@ -135,9 +144,9 @@ _GLIBCXX_END_NAMESPACE_CXX11
   inline copy_options&
   operator^=(copy_options& __x, copy_options __y) noexcept
   { return __x = __x ^ __y; }
+  /// @}
 
-
-  /// Bitmask type
+  /// Bitmask type representing file access permissions
   enum class perms : unsigned {
       none		=  0,
       owner_read	=  0400,
@@ -163,6 +172,8 @@ _GLIBCXX_END_NAMESPACE_CXX11
       symlink_nofollow	= 0x40000
   };
 
+  /// @{
+  /// @relates std::experimental::filesystem::perms
   constexpr perms
   operator&(perms __x, perms __y) noexcept
   {
@@ -205,12 +216,15 @@ _GLIBCXX_END_NAMESPACE_CXX11
   inline perms&
   operator^=(perms& __x, perms __y) noexcept
   { return __x = __x ^ __y; }
+  /// @}
 
-  // Bitmask type
+  /// Bitmask type controlling directory iteration
   enum class directory_options : unsigned char {
       none = 0, follow_directory_symlink = 1, skip_permission_denied = 2
   };
 
+  /// @{
+  /// @relates directory_options
   constexpr directory_options
   operator&(directory_options __x, directory_options __y) noexcept
   {
@@ -253,7 +267,9 @@ _GLIBCXX_END_NAMESPACE_CXX11
   inline directory_options&
   operator^=(directory_options& __x, directory_options __y) noexcept
   { return __x = __x ^ __y; }
+  /// @}
 
+  /// The type used for file timestamps
   using file_time_type = std::chrono::system_clock::time_point;
 
   // operational functions
diff --git a/libstdc++-v3/include/experimental/bits/fs_path.h b/libstdc++-v3/include/experimental/bits/fs_path.h
index 1fb84ec1e78..a2bc931c696 100644
--- a/libstdc++-v3/include/experimental/bits/fs_path.h
+++ b/libstdc++-v3/include/experimental/bits/fs_path.h
@@ -71,13 +71,13 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
   using std::basic_string_view;
 #endif
 
+  /// @cond undocumented
+namespace __detail
+{
   /** @addtogroup filesystem-ts
    *  @{
    */
 
-  /// @cond undocumented
-namespace __detail
-{
   template<typename _CharT,
 	   typename _Ch = typename remove_const<_CharT>::type>
     using __is_encoded_char
@@ -188,10 +188,16 @@ namespace __detail
 #endif
       >::value, _UnqualVal>::type;
 
+  /// @} group filesystem-ts
 } // namespace __detail
   /// @endcond
 
+  /** @addtogroup filesystem-ts
+   *  @{
+   */
+
   /// A filesystem path.
+  /// @ingroup filesystem-ts
   class path
   {
   public:
diff --git a/libstdc++-v3/include/ext/throw_allocator.h b/libstdc++-v3/include/ext/throw_allocator.h
index f4b3174dec6..6abef705f9a 100644
--- a/libstdc++-v3/include/ext/throw_allocator.h
+++ b/libstdc++-v3/include/ext/throw_allocator.h
@@ -73,7 +73,7 @@ namespace __gnu_cxx _GLIBCXX_VISIBILITY(default)
 _GLIBCXX_BEGIN_NAMESPACE_VERSION
 
   /**
-   *  @brief Thown by exception safety machinery.
+   *  @brief Thrown by utilities for testing exception safety.
    *  @ingroup exceptions
    */
   struct forced_error : public std::exception
diff --git a/libstdc++-v3/include/std/chrono b/libstdc++-v3/include/std/chrono
index 0b597be1944..a3290546f16 100644
--- a/libstdc++-v3/include/std/chrono
+++ b/libstdc++-v3/include/std/chrono
@@ -59,21 +59,32 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
    * @ingroup utilities
    *
    * Classes and functions for time.
-   * @{
+   *
+   * @since C++11
    */
 
   /** @namespace std::chrono
    *  @brief ISO C++ 2011 namespace for date and time utilities
+   *  @ingroup chrono
    */
   namespace chrono
   {
+    /// @addtogroup chrono
+    /// @{
+
+    /// `chrono::duration` represents a distance between two points in time
     template<typename _Rep, typename _Period = ratio<1>>
       struct duration;
 
+    /// `chrono::time_point` represents a point in time as measured by a clock
     template<typename _Clock, typename _Dur = typename _Clock::duration>
       struct time_point;
+    /// @}
   }
 
+  /// @addtogroup chrono
+  /// @{
+
   // 20.11.4.3 specialization of common_type (for duration, sfinae-friendly)
 
   /// @cond undocumented
@@ -99,8 +110,10 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
 
   /// @endcond
 
+  /// @{
+  /// @relates chrono::duration
+
   /// Specialization of common_type for chrono::duration types.
-  /// @relates duration
   template<typename _Rep1, typename _Period1, typename _Rep2, typename _Period2>
     struct common_type<chrono::duration<_Rep1, _Period1>,
 		       chrono::duration<_Rep2, _Period2>>
@@ -110,7 +123,6 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
     { };
 
   /// Specialization of common_type for two identical chrono::duration types.
-  /// @relates duration
   template<typename _Rep, typename _Period>
     struct common_type<chrono::duration<_Rep, _Period>,
 		       chrono::duration<_Rep, _Period>>
@@ -120,13 +132,13 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
     };
 
   /// Specialization of common_type for one chrono::duration type.
-  /// @relates duration
   template<typename _Rep, typename _Period>
     struct common_type<chrono::duration<_Rep, _Period>>
     {
       using type = chrono::duration<typename common_type<_Rep>::type,
 				    typename _Period::type>;
     };
+  /// @}
 
   // 20.11.4.3 specialization of common_type (for time_point, sfinae-friendly)
 
@@ -144,8 +156,10 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
 
   /// @endcond
 
+  /// @{
+  /// @relates chrono::time_point
+
   /// Specialization of common_type for chrono::time_point types.
-  /// @relates time_point
   template<typename _Clock, typename _Duration1, typename _Duration2>
     struct common_type<chrono::time_point<_Clock, _Duration1>,
 		       chrono::time_point<_Clock, _Duration2>>
@@ -153,17 +167,16 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
     { };
 
   /// Specialization of common_type for two identical chrono::time_point types.
-  /// @relates time_point
   template<typename _Clock, typename _Duration>
     struct common_type<chrono::time_point<_Clock, _Duration>,
 		       chrono::time_point<_Clock, _Duration>>
     { using type = chrono::time_point<_Clock, _Duration>; };
 
   /// Specialization of common_type for one chrono::time_point type.
-  /// @relates time_point
   template<typename _Clock, typename _Duration>
     struct common_type<chrono::time_point<_Clock, _Duration>>
     { using type = chrono::time_point<_Clock, _Duration>; };
+  /// @}
 
   /// @} group chrono
 
@@ -442,7 +455,6 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
 
     /// @endcond
 
-    /// duration
     template<typename _Rep, typename _Period>
       struct duration
       {
@@ -623,7 +635,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
 	rep __r;
       };
 
-    /// @relates duration @{
+    /// @{
+    /// @relates std::chrono::duration
 
     /// The sum of two durations.
     template<typename _Rep1, typename _Period1,
@@ -668,9 +681,11 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
 
     /// @endcond
 
-    /// @relates duration @{
+    /** @{
+     * Arithmetic operators for chrono::duration
+     * @relates std::chrono::duration
+     */
 
-    /// Multiply a duration by a scalar value.
     template<typename _Rep1, typename _Period, typename _Rep2>
       constexpr duration<__common_rep_t<_Rep1, _Rep2>, _Period>
       operator*(const duration<_Rep1, _Period>& __d, const _Rep2& __s)
@@ -680,7 +695,6 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
 	return __cd(__cd(__d).count() * __s);
       }
 
-    /// Multiply a duration by a scalar value.
     template<typename _Rep1, typename _Rep2, typename _Period>
       constexpr duration<__common_rep_t<_Rep2, _Rep1>, _Period>
       operator*(const _Rep1& __s, const duration<_Rep2, _Period>& __d)
@@ -731,9 +745,15 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
 	typedef typename common_type<__dur1,__dur2>::type	__cd;
 	return __cd(__cd(__lhs).count() % __cd(__rhs).count());
       }
+    /// @}
 
     // comparisons
 
+    /** @{
+     * Comparisons for chrono::duration
+     * @relates std::chrono::duration
+     */
+
     template<typename _Rep1, typename _Period1,
 	     typename _Rep2, typename _Period2>
       constexpr bool
@@ -802,6 +822,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
 
     /// @}
 
+    /// @cond undocumented
 #ifdef _GLIBCXX_USE_C99_STDINT_TR1
 # define _GLIBCXX_CHRONO_INT64_T int64_t
 #elif defined __INT64_TYPE__
@@ -811,6 +832,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
 	"Representation type for nanoseconds must have at least 64 bits");
 # define _GLIBCXX_CHRONO_INT64_T long long
 #endif
+    /// @endcond
 
     /// nanoseconds
     using nanoseconds	= duration<_GLIBCXX_CHRONO_INT64_T, nano>;
@@ -846,7 +868,6 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
 
 #undef _GLIBCXX_CHRONO_INT64_T
 
-    /// time_point
     template<typename _Clock, typename _Dur>
       struct time_point
       {
@@ -970,7 +991,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
       }
 #endif // C++17
 
-    /// @relates time_point @{
+    /// @{
+    /// @relates time_point
 
     /// Adjust a time point forwards by the given duration.
     template<typename _Clock, typename _Dur1,
@@ -1014,16 +1036,18 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
 	return __time_point(__lhs.time_since_epoch() -__rhs);
       }
 
-    /// @}
-
-    /// @relates time_point @{
-
     /// The difference between two time points (as a duration)
     template<typename _Clock, typename _Dur1, typename _Dur2>
       constexpr typename common_type<_Dur1, _Dur2>::type
       operator-(const time_point<_Clock, _Dur1>& __lhs,
 		const time_point<_Clock, _Dur2>& __rhs)
       { return __lhs.time_since_epoch() - __rhs.time_since_epoch(); }
+    /// @}
+
+    /** @{
+     * Comparisons for time_point
+     * @relates chrono::time_point
+     */
 
     template<typename _Clock, typename _Dur1, typename _Dur2>
       constexpr bool
@@ -3135,7 +3159,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
       };
 #endif // C++20
 
-    /// @}
+    /// @} group chrono
   } // namespace chrono
 
 #if __cplusplus > 201103L
@@ -3169,6 +3193,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
    */
   inline namespace chrono_literals
   {
+    /// @addtogroup chrono
+    /// @{
+
 #pragma GCC diagnostic push
 #pragma GCC diagnostic ignored "-Wliteral-suffix"
     /// @cond undocumented
@@ -3260,6 +3287,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
 #endif // C++20
 
 #pragma GCC diagnostic pop
+    /// @}
   } // inline namespace chrono_literals
   } // inline namespace literals
 
@@ -3271,6 +3299,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
 #if __cplusplus > 201703L
   namespace chrono
   {
+    /// @addtogroup chrono
+    /// @{
+
     // 12/24 HOURS FUNCTIONS
 
     constexpr bool
@@ -3309,7 +3340,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
 	    return __h + 12h;
 	}
     }
-  }
+    /// @} group chrono
+  } // namespace chrono
 #endif
 
 #if __cplusplus >= 201703L
diff --git a/libstdc++-v3/include/std/system_error b/libstdc++-v3/include/std/system_error
index 8c10a89ab46..142af7100d0 100644
--- a/libstdc++-v3/include/std/system_error
+++ b/libstdc++-v3/include/std/system_error
@@ -48,7 +48,7 @@ namespace std _GLIBCXX_VISIBILITY(default)
 _GLIBCXX_BEGIN_NAMESPACE_VERSION
 
   /** @addtogroup diagnostics
-   *  @{
+   * @{
    */
 
   class error_code;
@@ -75,8 +75,14 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
     inline constexpr bool is_error_condition_enum_v =
       is_error_condition_enum<_Tp>::value;
 #endif // C++17
+  /// @}
+
   inline namespace _V2 {
 
+  /** @addtogroup diagnostics
+   * @{
+   */
+
   /** Abstract base class for types defining a category of error codes.
    *
    * An error category defines a context that give meaning to the integer
@@ -85,6 +91,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
    * associated with the "generic" category and other OS-specific error
    * numbers are associated with the "system" category, but a user-defined
    * category might give different meanings to the same numerical values.
+   *
+   * @since C++11
    */
   class error_category
   {
@@ -159,8 +167,13 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
   /// Error category for other error codes defined by the OS.
   _GLIBCXX_CONST const error_category& system_category() noexcept;
 
+  /// @}
   } // end inline namespace
 
+  /** @addtogroup diagnostics
+   * @{
+   */
+
   error_code make_error_code(errc) noexcept;
 
   /** Class error_code
@@ -176,6 +189,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
    * an `errno` value and the "generic" category, but errors from an HTTP
    * library might be represented by an HTTP response status code (e.g. 404)
    * and a custom category defined by the library.
+   *
+   * @since C++11
+   * @ingroup diagnostics
    */
   class error_code
   {
@@ -275,6 +291,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
    *
    * An `error_condition` represents something that the program can test for,
    * and subsequently take appropriate action.
+   *
+   * @since C++11
    */
   class error_condition
   {
@@ -346,7 +364,6 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
 	    && __lhs.value() == __rhs.value()); }
 
   /// @relates error_code
-  /// @relates error_condition
   inline bool
   operator==(const error_code& __lhs, const error_condition& __rhs) noexcept
   {
@@ -386,7 +403,6 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
 		&& __lhs.value() < __rhs.value()));
   }
 
-  /// @relates error_code
   /// @relates error_condition
   inline bool
   operator==(const error_condition& __lhs, const error_code& __rhs) noexcept
@@ -401,12 +417,10 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
   { return !(__lhs == __rhs); }
 
   /// @relates error_code
-  /// @relates error_condition
   inline bool
   operator!=(const error_code& __lhs, const error_condition& __rhs) noexcept
   { return !(__lhs == __rhs); }
 
-  /// @relates error_code
   /// @relates error_condition
   inline bool
   operator!=(const error_condition& __lhs, const error_code& __rhs) noexcept
@@ -418,6 +432,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
 	     const error_condition& __rhs) noexcept
   { return !(__lhs == __rhs); }
 #endif // three_way_comparison
+  /// @}
 
   /**
    * @brief An exception type that includes an `error_code` value.
@@ -425,6 +440,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
    * Typically used to report errors from the operating system and other
    * low-level APIs.
    *
+   * @since C++11
    * @ingroup exceptions
    */
   class system_error : public std::runtime_error
diff --git a/libstdc++-v3/libsupc++/exception b/libstdc++-v3/libsupc++/exception
index 7c6d90ec525..a023e22ea89 100644
--- a/libstdc++-v3/libsupc++/exception
+++ b/libstdc++-v3/libsupc++/exception
@@ -46,7 +46,10 @@ namespace std
    */
 
   /** If an %exception is thrown which is not listed in a function's
-   *  %exception specification, one of these may be thrown.  */
+   *  %exception specification, one of these may be thrown.
+   *
+   *  @ingroup exceptions
+   */
   class bad_exception : public exception
   {
   public:
@@ -93,13 +96,13 @@ namespace std
 
   /** [18.6.4]/1:  'Returns true after completing evaluation of a
    *  throw-expression until either completing initialization of the
-   *  exception-declaration in the matching handler or entering @c unexpected()
-   *  due to the throw; or after entering @c terminate() for any reason
-   *  other than an explicit call to @c terminate().  [Note: This includes
+   *  exception-declaration in the matching handler or entering `unexpected()`
+   *  due to the throw; or after entering `terminate()` for any reason
+   *  other than an explicit call to `terminate()`.  [Note: This includes
    *  stack unwinding [15.2].  end note]'
    *
-   *  2: 'When @c uncaught_exception() is true, throwing an
-   *  %exception can result in a call of @c terminate()
+   *  2: 'When `uncaught_exception()` is true, throwing an
+   *  %exception can result in a call of 1terminate()`
    *  (15.5.1).'
    */
   _GLIBCXX17_DEPRECATED
@@ -107,7 +110,10 @@ namespace std
 
 #if __cplusplus >= 201703L || !defined(__STRICT_ANSI__) // c++17 or gnu++98
 #define __cpp_lib_uncaught_exceptions 201411L
-  /// The number of uncaught exceptions.
+  /** The number of uncaught exceptions.
+   *  @since C++17, or any non-strict mode, e.g. `-std=gnu++98`
+   *  @see uncaught_exception()
+   */
   int uncaught_exceptions() _GLIBCXX_USE_NOEXCEPT __attribute__ ((__pure__));
 #endif
 
diff --git a/libstdc++-v3/libsupc++/exception.h b/libstdc++-v3/libsupc++/exception.h
index 373ce3fef57..60faa8836b8 100644
--- a/libstdc++-v3/libsupc++/exception.h
+++ b/libstdc++-v3/libsupc++/exception.h
@@ -44,6 +44,7 @@ namespace std
   /**
    * @defgroup exceptions Exceptions
    * @ingroup diagnostics
+   * @since C++98
    *
    * Classes and functions for reporting errors via exceptions.
    * @{

^ permalink raw reply	[flat|nested] only message in thread

only message in thread, other threads:[~2021-07-01 18:25 UTC | newest]

Thread overview: (only message) (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-07-01 18:25 [committed] libstdc++: Improvements to Doxygen markup Jonathan Wakely

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).