From 9b12491c1901b8b337093132479e8bf387afd31e Mon Sep 17 00:00:00 2001 From: Victor Zverovich Date: Sun, 2 Jun 2024 14:20:41 -0700 Subject: [PATCH] Migrate docs --- include/fmt/args.h | 86 +++++++++++++--------------- include/fmt/os.h | 126 ++++++++++++++++++------------------------ include/fmt/ostream.h | 26 ++++----- include/fmt/printf.h | 63 ++++++++------------- 4 files changed, 125 insertions(+), 176 deletions(-) diff --git a/include/fmt/args.h b/include/fmt/args.h index 390393c8..10c1eb8f 100644 --- a/include/fmt/args.h +++ b/include/fmt/args.h @@ -67,14 +67,10 @@ class dynamic_arg_list { } // namespace detail /** - \rst - A dynamic version of `fmt::format_arg_store`. - It's equipped with a storage to potentially temporary objects which lifetimes - could be shorter than the format arguments object. - - It can be implicitly converted into `~fmt::basic_format_args` for passing - into type-erased formatting functions such as `~fmt::vformat`. - \endrst + * A dynamic list of formatting arguments with storage. + * + * It can be implicitly converted into `fmt::basic_format_args` for passing + * into type-erased formatting functions such as `fmt::vformat`. */ template class dynamic_format_arg_store @@ -152,22 +148,20 @@ class dynamic_format_arg_store constexpr dynamic_format_arg_store() = default; /** - \rst - Adds an argument into the dynamic store for later passing to a formatting - function. - - Note that custom types and string types (but not string views) are copied - into the store dynamically allocating memory if necessary. - - **Example**: - - fmt::dynamic_format_arg_store store; - store.push_back(42); - store.push_back("abc"); - store.push_back(1.5f); - std::string result = fmt::vformat("{} and {} and {}", store); - \endrst - */ + * Adds an argument into the dynamic store for later passing to a formatting + * function. + * + * Note that custom types and string types (but not string views) are copied + * into the store dynamically allocating memory if necessary. + * + * **Example**: + * + * fmt::dynamic_format_arg_store store; + * store.push_back(42); + * store.push_back("abc"); + * store.push_back(1.5f); + * std::string result = fmt::vformat("{} and {} and {}", store); + */ template void push_back(const T& arg) { if (detail::const_check(need_copy::value)) emplace_arg(dynamic_args_.push>(arg)); @@ -176,20 +170,18 @@ class dynamic_format_arg_store } /** - \rst - Adds a reference to the argument into the dynamic store for later passing to - a formatting function. - - **Example**: - - fmt::dynamic_format_arg_store store; - char band[] = "Rolling Stones"; - store.push_back(std::cref(band)); - band[9] = 'c'; // Changing str affects the output. - std::string result = fmt::vformat("{}", store); - // result == "Rolling Scones" - \endrst - */ + * Adds a reference to the argument into the dynamic store for later passing + * to a formatting function. + * + * **Example**: + * + * fmt::dynamic_format_arg_store store; + * char band[] = "Rolling Stones"; + * store.push_back(std::cref(band)); + * band[9] = 'c'; // Changing str affects the output. + * std::string result = fmt::vformat("{}", store); + * // result == "Rolling Scones" + */ template void push_back(std::reference_wrapper arg) { static_assert( need_copy::value, @@ -198,10 +190,10 @@ class dynamic_format_arg_store } /** - Adds named argument into the dynamic store for later passing to a formatting - function. ``std::reference_wrapper`` is supported to avoid copying of the - argument. The name is always copied into the store. - */ + * Adds named argument into the dynamic store for later passing to a + * formatting function. `std::reference_wrapper` is supported to avoid + * copying of the argument. The name is always copied into the store. + */ template void push_back(const detail::named_arg& arg) { const char_type* arg_name = @@ -214,19 +206,15 @@ class dynamic_format_arg_store } } - /** Erase all elements from the store */ + /// Erase all elements from the store. void clear() { data_.clear(); named_info_.clear(); dynamic_args_ = detail::dynamic_arg_list(); } - /** - \rst - Reserves space to store at least `new_cap` arguments including - `new_cap_named` named arguments. - \endrst - */ + /// Reserves space to store at least `new_cap` arguments including + /// `new_cap_named` named arguments. void reserve(size_t new_cap, size_t new_cap_named) { FMT_ASSERT(new_cap >= new_cap_named, "Set of arguments includes set of named arguments"); diff --git a/include/fmt/os.h b/include/fmt/os.h index 44350646..fae18f16 100644 --- a/include/fmt/os.h +++ b/include/fmt/os.h @@ -79,46 +79,33 @@ FMT_BEGIN_NAMESPACE FMT_BEGIN_EXPORT /** - \rst - A reference to a null-terminated string. It can be constructed from a C - string or ``std::string``. - - You can use one of the following type aliases for common character types: - - +---------------+-----------------------------+ - | Type | Definition | - +===============+=============================+ - | cstring_view | basic_cstring_view | - +---------------+-----------------------------+ - | wcstring_view | basic_cstring_view | - +---------------+-----------------------------+ - - This class is most useful as a parameter type to allow passing - different types of strings to a function, for example:: - - template - std::string format(cstring_view format_str, const Args & ... args); - - format("{}", 42); - format(std::string("{}"), 42); - \endrst + * A reference to a null-terminated string. It can be constructed from a C + * string or `std::string`. + * + * You can use one of the following type aliases for common character types: + * + * +---------------+-----------------------------+ + * | Type | Definition | + * +===============+=============================+ + * | cstring_view | basic_cstring_view | + * +---------------+-----------------------------+ + * | wcstring_view | basic_cstring_view | + * +---------------+-----------------------------+ + * + * This class is most useful as a parameter type for functions that wrap C APIs. */ template class basic_cstring_view { private: const Char* data_; public: - /** Constructs a string reference object from a C string. */ + /// Constructs a string reference object from a C string. basic_cstring_view(const Char* s) : data_(s) {} - /** - \rst - Constructs a string reference from an ``std::string`` object. - \endrst - */ + /// Constructs a string reference from an `std::string` object. basic_cstring_view(const std::basic_string& s) : data_(s.c_str()) {} - /** Returns the pointer to a C string. */ + /// Returns the pointer to a C string. auto c_str() const -> const Char* { return data_; } }; @@ -137,33 +124,30 @@ FMT_API std::system_error vwindows_error(int error_code, string_view format_str, format_args args); /** - \rst - Constructs a :class:`std::system_error` object with the description - of the form - - .. parsed-literal:: - **: ** - - where ** is the formatted message and ** is the - system message corresponding to the error code. - `error_code` is a Windows error code as given by ``GetLastError``. - If `error_code` is not a valid error code such as -1, the system message - will look like "error -1". - - **Example**: - - // This throws a system_error with the description - // cannot open file 'madeup': The system cannot find the file specified. - // or similar (system message may vary). - const char *filename = "madeup"; - LPOFSTRUCT of = LPOFSTRUCT(); - HFILE file = OpenFile(filename, &of, OF_READ); - if (file == HFILE_ERROR) { - throw fmt::windows_error(GetLastError(), - "cannot open file '{}'", filename); - } - \endrst -*/ + * Constructs a `std::system_error` object with the description of the form + * + * : + * + * where `` is the formatted message and `` is the + * system message corresponding to the error code. + * `error_code` is a Windows error code as given by `GetLastError`. + * If `error_code` is not a valid error code such as -1, the system message + * will look like "error -1". + * + * **Example**: + * + * // This throws a system_error with the description + * // cannot open file 'madeup': The system cannot find the file + * specified. + * // or similar (system message may vary). + * const char *filename = "madeup"; + * LPOFSTRUCT of = LPOFSTRUCT(); + * HFILE file = OpenFile(filename, &of, OF_READ); + * if (file == HFILE_ERROR) { + * throw fmt::windows_error(GetLastError(), + * "cannot open file '{}'", filename); + * } + */ template std::system_error windows_error(int error_code, string_view message, const Args&... args) { @@ -401,9 +385,7 @@ class file_buffer final : public buffer { } // namespace detail -// Added {} below to work around default constructor error known to -// occur in Xcode versions 7.2.1 and 8.2.1. -constexpr detail::buffer_size buffer_size{}; +constexpr auto buffer_size = detail::buffer_size(); /// A fast output stream for writing from a single thread. Writing from /// multiple threads without external synchronization may result in a data race. @@ -435,19 +417,17 @@ class FMT_API ostream { }; /** - \rst - Opens a file for writing. Supported parameters passed in `params`: - - * ````: Flags passed to `open - `_ - (``file::WRONLY | file::CREATE | file::TRUNC`` by default) - * ``buffer_size=``: Output buffer size - - **Example**: - - auto out = fmt::output_file("guide.txt"); - out.print("Don't {}", "Panic"); - \endrst + * Opens a file for writing. Supported parameters passed in `params`: + * + * - ``: Flags passed to [open]( + * https://pubs.opengroup.org/onlinepubs/007904875/functions/open.html) + * (`file::WRONLY | file::CREATE | file::TRUNC` by default) + * - `buffer_size=`: Output buffer size + * + * **Example**: + * + * auto out = fmt::output_file("guide.txt"); + * out.print("Don't {}", "Panic"); */ template inline auto output_file(cstring_view path, T... params) -> ostream { diff --git a/include/fmt/ostream.h b/include/fmt/ostream.h index a5f5a5fe..f05e0dcd 100644 --- a/include/fmt/ostream.h +++ b/include/fmt/ostream.h @@ -136,14 +136,12 @@ struct formatter, Char> }; /** - \rst - Returns a view that formats `value` via an ostream ``operator<<``. - - **Example**: - - fmt::print("Current thread id: {}\n", - fmt::streamed(std::this_thread::get_id())); - \endrst + * Returns a view that formats `value` via an ostream `operator<<`. + * + * **Example**: + * + * fmt::print("Current thread id: {}\n", + * fmt::streamed(std::this_thread::get_id())); */ template constexpr auto streamed(const T& value) -> detail::streamed_view { @@ -172,13 +170,11 @@ void vprint(std::basic_ostream& os, } /** - \rst - Prints formatted data to the stream `os`. - - **Example**: - - fmt::print(cerr, "Don't {}!", "panic"); - \endrst + * Prints formatted data to the stream `os`. + * + * **Example**: + * + * fmt::print(cerr, "Don't {}!", "panic"); */ FMT_EXPORT template void print(std::ostream& os, format_string fmt, T&&... args) { diff --git a/include/fmt/printf.h b/include/fmt/printf.h index 5cdb6546..e6cd5c3d 100644 --- a/include/fmt/printf.h +++ b/include/fmt/printf.h @@ -36,12 +36,8 @@ template class basic_printf_context { using parse_context_type = basic_format_parse_context; template using formatter_type = printf_formatter; - /** - \rst - Constructs a ``printf_context`` object. References to the arguments are - stored in the context object so make sure they have appropriate lifetimes. - \endrst - */ + /// Constructs a `printf_context` object. References to the arguments are + /// stored in the context object so make sure they have appropriate lifetimes. basic_printf_context(basic_appender out, basic_format_args args) : out_(out), args_(args) {} @@ -227,7 +223,7 @@ auto make_arg_formatter(basic_appender iter, format_specs& s) return {iter, s, locale_ref()}; } -// The ``printf`` argument formatter. +// The `printf` argument formatter. template class printf_arg_formatter : public arg_formatter { private: @@ -276,7 +272,6 @@ class printf_arg_formatter : public arg_formatter { base::operator()(value); } - /** Formats a null-terminated C string. */ void operator()(const char* value) { if (value) base::operator()(value); @@ -284,7 +279,6 @@ class printf_arg_formatter : public arg_formatter { write_null_pointer(this->specs.type != presentation_type::pointer); } - /** Formats a null-terminated wide C string. */ void operator()(const wchar_t* value) { if (value) base::operator()(value); @@ -294,7 +288,6 @@ class printf_arg_formatter : public arg_formatter { void operator()(basic_string_view value) { base::operator()(value); } - /** Formats a pointer. */ void operator()(const void* value) { if (value) base::operator()(value); @@ -302,7 +295,6 @@ class printf_arg_formatter : public arg_formatter { write_null_pointer(); } - /** Formats an argument of a custom (user-defined) type. */ void operator()(typename basic_format_arg::handle handle) { auto parse_ctx = basic_format_parse_context({}); handle.format(parse_ctx, context_); @@ -573,12 +565,8 @@ using wprintf_context = basic_printf_context; using printf_args = basic_format_args; using wprintf_args = basic_format_args; -/** - \rst - Constructs an `~fmt::format_arg_store` object that contains references to - arguments and can be implicitly converted to `~fmt::printf_args`. - \endrst - */ +/// Constructs an `format_arg_store` object that contains references to +/// arguments and can be implicitly converted to `printf_args`. template inline auto make_printf_args(T&... args) -> decltype(make_format_args>(args...)) { @@ -599,14 +587,13 @@ inline auto vsprintf(basic_string_view fmt, } /** - \rst - Formats arguments and returns the result as a string. - - **Example**: - - std::string message = fmt::sprintf("The answer is %d", 42); - \endrst -*/ + * Formats `args` according to specifications in `fmt` and returns the result + * as as string. + * + * **Example**: + * + * std::string message = fmt::sprintf("The answer is %d", 42); + */ template > inline auto sprintf(const S& fmt, const T&... args) -> std::basic_string { return vsprintf(detail::to_string_view(fmt), @@ -625,13 +612,12 @@ inline auto vfprintf(std::FILE* f, basic_string_view fmt, } /** - \rst - Prints formatted data to the file `f`. - - **Example**: - - fmt::fprintf(stderr, "Don't %s!", "panic"); - \endrst + * Formats `args` according to specifications in `fmt` and writes the output + * to `f`. + * + * **Example**: + * + * fmt::fprintf(stderr, "Don't %s!", "panic"); */ template > inline auto fprintf(std::FILE* f, const S& fmt, const T&... args) -> int { @@ -647,13 +633,12 @@ FMT_DEPRECATED inline auto vprintf(basic_string_view fmt, } /** - \rst - Prints formatted data to ``stdout``. - - **Example**: - - fmt::printf("Elapsed time: %.2f seconds", 1.23); - \endrst + * Formats `args` according to specifications in `fmt` and writes the output + * to `stdout`. + * + * **Example**: + * + * fmt::printf("Elapsed time: %.2f seconds", 1.23); */ template inline auto printf(string_view fmt, const T&... args) -> int {