Improve docs for C++17 Filesystem library

	* include/bits/fs_dir.h: Fix/improve doxygen markup.
	* include/bits/fs_fwd.h: Likewise.
	* include/bits/fs_ops.h: Likewise.
	* include/bits/fs_path.h: Likewise.
	* include/std/filesystem: Likewise.

From-SVN: r270811

6 files changed, 75 insertions, 28 deletions

diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog
index fa36076..52d3adf 100644
--- a/libstdc++-v3/ChangeLog
+++ b/libstdc++-v3/ChangeLog
@@ -1,5 +1,11 @@
 2019-05-02  Jonathan Wakely  <jwakely@redhat.com>
 
+	* include/bits/fs_dir.h: Fix/improve doxygen markup.
+	* include/bits/fs_fwd.h: Likewise.
+	* include/bits/fs_ops.h: Likewise.
+	* include/bits/fs_path.h: Likewise.
+	* include/std/filesystem: Likewise.
+
 	* include/experimental/bits/net.h: Fix/improve doxygen markup.
 	* include/experimental/buffer: Likewise.
 	* include/experimental/executor: Likewise.
diff --git a/libstdc++-v3/include/bits/fs_dir.h b/libstdc++-v3/include/bits/fs_dir.h
index 69f0eb8..faf0452 100644
--- a/libstdc++-v3/include/bits/fs_dir.h
+++ b/libstdc++-v3/include/bits/fs_dir.h
@@ -42,11 +42,11 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
 
 namespace filesystem
 {
-  /**
-   * @ingroup filesystem
-   * @{
+  /** @addtogroup filesystem
+   *  @{
    */
 
+  /// Information about a file's type and permissions.
   class file_status
   {
   public:
@@ -83,6 +83,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
   class directory_iterator;
   class recursive_directory_iterator;
 
+  /// The value type used by directory iterators
   class directory_entry
   {
   public:
@@ -337,6 +338,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
     file_type		_M_type = file_type::none;
   };
 
+  /// Proxy returned by post-increment on directory iterators.
   struct __directory_iterator_proxy
   {
     const directory_entry& operator*() const& noexcept { return _M_entry; }
@@ -353,6 +355,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
     directory_entry _M_entry;
   };
 
+  /// Iterator type for traversing the entries in a single directory.
   class directory_iterator
   {
   public:
@@ -423,14 +426,23 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
     std::__shared_ptr<_Dir> _M_dir;
   };
 
+  /// @relates std::filesystem::directory_iterator @{
+
+  /** @brief Enable range-based `for` using directory_iterator.
+   *
+   *  e.g. `for (auto& entry : std::filesystem::directory_iterator(".")) ...`
+   */
   inline directory_iterator
   begin(directory_iterator __iter) noexcept
   { return __iter; }
 
+  /// Return a past-the-end directory_iterator
   inline directory_iterator
   end(directory_iterator) noexcept
   { return directory_iterator(); }
+  // @}
 
+  /// Iterator type for recursively traversing a directory hierarchy.
   class recursive_directory_iterator
   {
   public:
@@ -512,13 +524,21 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
     std::__shared_ptr<_Dir_stack> _M_dirs;
   };
 
+  /// @relates std::filesystem::recursive_directory_iterator @{
+
+  /** @brief Enable range-based `for` using recursive_directory_iterator.
+   *
+   *  e.g. `for (auto& entry : recursive_directory_iterator(".")) ...`
+   */
   inline recursive_directory_iterator
   begin(recursive_directory_iterator __iter) noexcept
   { return __iter; }
 
+  /// Return a past-the-end recursive_directory_iterator
   inline recursive_directory_iterator
   end(recursive_directory_iterator) noexcept
   { return recursive_directory_iterator(); }
+  // @}
 
 _GLIBCXX_END_NAMESPACE_CXX11
 
diff --git a/libstdc++-v3/include/bits/fs_fwd.h b/libstdc++-v3/include/bits/fs_fwd.h
index a0e3d73..bb339c4 100644
--- a/libstdc++-v3/include/bits/fs_fwd.h
+++ b/libstdc++-v3/include/bits/fs_fwd.h
@@ -40,20 +40,17 @@ 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
 inline namespace __cxx11 __attribute__((__abi_tag__ ("cxx11"))) { }
 #endif
 
-  /**
-   * @defgroup filesystem Filesystem
-   *
-   * Utilities for performing operations on file systems and their components,
-   * such as paths, regular files, and directories.
-   *
-   * @{
-   */
 
   class file_status;
 _GLIBCXX_BEGIN_NAMESPACE_CXX11
@@ -379,12 +376,9 @@ _GLIBCXX_END_NAMESPACE_CXX11
   bool is_regular_file(file_status) noexcept;
   bool is_symlink(file_status) noexcept;
 
-  // @} group filesystem
 } // namespace filesystem
-
+// @}
 _GLIBCXX_END_NAMESPACE_VERSION
 } // namespace std
-
 #endif // C++17
-
 #endif // _GLIBCXX_FS_FWD_H
diff --git a/libstdc++-v3/include/bits/fs_ops.h b/libstdc++-v3/include/bits/fs_ops.h
index ee16499..66c6200 100644
--- a/libstdc++-v3/include/bits/fs_ops.h
+++ b/libstdc++-v3/include/bits/fs_ops.h
@@ -40,9 +40,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
 
 namespace filesystem
 {
-  /**
-   * @ingroup filesystem
-   * @{
+  /** @addtogroup filesystem
+   *  @{
    */
 
   path absolute(const path& __p);
diff --git a/libstdc++-v3/include/bits/fs_path.h b/libstdc++-v3/include/bits/fs_path.h
index 28878c6..d1ad11a 100644
--- a/libstdc++-v3/include/bits/fs_path.h
+++ b/libstdc++-v3/include/bits/fs_path.h
@@ -59,9 +59,8 @@ namespace filesystem
 {
 _GLIBCXX_BEGIN_NAMESPACE_CXX11
 
-  /**
-   * @ingroup filesystem
-   * @{
+  /** @addtogroup filesystem
+   *  @{
    */
 
   /// A filesystem path.
@@ -158,14 +157,20 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
 
   public:
 #ifdef _GLIBCXX_FILESYSTEM_IS_WINDOWS
-    typedef wchar_t				value_type;
-    static constexpr value_type			preferred_separator = L'\\';
+    using value_type = wchar_t;
+    static constexpr value_type preferred_separator = L'\\';
 #else
-    typedef char				value_type;
-    static constexpr value_type			preferred_separator = '/';
+# ifdef _GLIBCXX_DOXYGEN
+    /// Windows uses wchar_t for path::value_type, POSIX uses char.
+    using value_type = __os_dependent__;
+# else
+    using value_type =  char;
+# endif
+    static constexpr value_type preferred_separator = '/';
 #endif
-    typedef std::basic_string<value_type>	string_type;
+    using string_type = std::basic_string<value_type>;
 
+    /// path::format is ignored in this implementation
     enum format : unsigned char { native_format, generic_format, auto_format };
 
     // constructors and destructor
@@ -392,7 +397,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
 
     // iterators
     class iterator;
-    typedef iterator const_iterator;
+    using const_iterator = iterator;
 
     iterator begin() const;
     iterator end() const;
@@ -451,6 +456,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
       return __result;
     }
 
+    /// @cond undocumented
     // Create a basic_string by reading until a null character.
     template<typename _InputIterator,
 	     typename _Traits = std::iterator_traits<_InputIterator>,
@@ -464,6 +470,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
 	  __str.push_back(__ch);
 	return __str;
       }
+    /// @endcond
 
   private:
     enum class _Type : unsigned char {
@@ -608,10 +615,13 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
     struct _Parser;
   };
 
+  /// @relates std::filesystem::path @{
+
   inline void swap(path& __lhs, path& __rhs) noexcept { __lhs.swap(__rhs); }
 
   size_t hash_value(const path& __p) noexcept;
 
+  /// Create a path from a UTF-8-encoded sequence of char
   template<typename _InputIterator>
     inline auto
     u8path(_InputIterator __first, _InputIterator __last)
@@ -638,6 +648,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
 #endif
     }
 
+  /// Create a path from a UTF-8-encoded sequence of char
   template<typename _Source>
     inline auto
     u8path(const _Source& __source)
@@ -659,6 +670,9 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
 #endif
     }
 
+  /// @}
+
+  /// Exception type thrown by the Filesystem library
   class filesystem_error : public std::system_error
   {
   public:
@@ -687,6 +701,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
     std::__shared_ptr<const _Impl> _M_impl;
   };
 
+  /// @cond undocumented
+
   struct path::_Cmpt : path
   {
     _Cmpt(basic_string_view<value_type> __s, _Type __t, size_t __pos)
@@ -796,6 +812,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
 	{ return _S_convert(__first.base(), __last.base()); }
     };
 
+  /// @endcond
+
   /// An iterator for the components of a path
   class path::iterator
   {
@@ -948,6 +966,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
     _M_cmpts.swap(__rhs._M_cmpts);
   }
 
+  /// @cond undocumented
   template<typename _CharT, typename _Traits, typename _Allocator>
     std::basic_string<_CharT, _Traits, _Allocator>
     path::_S_str_convert(const string_type& __str, const _Allocator& __a)
@@ -1012,6 +1031,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
 	    "Cannot convert character sequence",
 	    std::make_error_code(errc::illegal_byte_sequence)));
     }
+  /// @endcond
 
   template<typename _CharT, typename _Traits, typename _Allocator>
     inline basic_string<_CharT, _Traits, _Allocator>
diff --git a/libstdc++-v3/include/std/filesystem b/libstdc++-v3/include/std/filesystem
index 9b724a7..52ef476 100644
--- a/libstdc++-v3/include/std/filesystem
+++ b/libstdc++-v3/include/std/filesystem
@@ -22,8 +22,9 @@
 // see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see
 // <http://www.gnu.org/licenses/>.
 
-/** @file filesystem
+/** @file include/filesystem
  *  This is a Standard C++ Library header.
+ *  @ingroup filesystem
  */
 
 #ifndef _GLIBCXX_FILESYSTEM
@@ -33,6 +34,13 @@
 
 #if __cplusplus >= 201703L
 
+/**
+ * @defgroup filesystem File System
+ *
+ * Utilities for performing operations on file systems and their components,
+ * such as paths, regular files, and directories.
+ */
+
 #include <bits/fs_fwd.h>
 #include <bits/fs_path.h>
 #include <bits/fs_dir.h>