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.

2 files changed, 29 insertions, 7 deletions

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: