Skip to content

R
riscv-gcc-1
Commit d727fdc4 by Jonathan Wakely Committed by Jonathan Wakely
Options

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