From d727fdc42bbf1ea23bfda42b9c0c87c2cb8e93b9 Mon Sep 17 00:00:00 2001 From: Jonathan Wakely Date: Thu, 2 May 2019 16:46:38 +0100 Subject: [PATCH] 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 --- libstdc++-v3/ChangeLog | 6 +++++ libstdc++-v3/include/bits/fs_dir.h | 26 +++++++++++++++++--- libstdc++-v3/include/bits/fs_fwd.h | 18 +++++--------- libstdc++-v3/include/bits/fs_ops.h | 5 ++-- libstdc++-v3/include/bits/fs_path.h | 38 ++++++++++++++++++++++------- libstdc++-v3/include/std/filesystem | 10 +++++++- 6 files changed, 75 insertions(+), 28 deletions(-) diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog index fa360761165..52d3adf251e 100644 --- a/libstdc++-v3/ChangeLog +++ b/libstdc++-v3/ChangeLog @@ -1,5 +1,11 @@ 2019-05-02 Jonathan Wakely + * 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 69f0eb825fe..faf0452d4d1 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 a0e3d73e2a3..bb339c44144 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 ee16499a9f9..66c6200388a 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 28878c627a7..d1ad11a60c4 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 string_type; + using string_type = std::basic_string; + /// 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, @@ -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 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 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 _M_impl; }; + /// @cond undocumented + struct path::_Cmpt : path { _Cmpt(basic_string_view __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 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 inline basic_string<_CharT, _Traits, _Allocator> diff --git a/libstdc++-v3/include/std/filesystem b/libstdc++-v3/include/std/filesystem index 9b724a73e8c..52ef476d55d 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 // . -/** @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 #include #include -- 2.30.2