Migrate docs

include/fmt/args.h

@@ -67,14 +67,10 @@ class dynamic_arg_list {
 }  // namespace detail
 
 /**
-  \rst
+ * A dynamic list of formatting arguments with storage.
-  A dynamic version of `fmt::format_arg_store`.
+ *
-  It's equipped with a storage to potentially temporary objects which lifetimes
+ * It can be implicitly converted into `fmt::basic_format_args` for passing
-  could be shorter than the format arguments object.
+ * into type-erased formatting functions such as `fmt::vformat`.
-
-  It can be implicitly converted into `~fmt::basic_format_args` for passing
-  into type-erased formatting functions such as `~fmt::vformat`.
-  \endrst
  */
 template <typename Context>
 class dynamic_format_arg_store
@@ -152,21 +148,19 @@ 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
-    Adds an argument into the dynamic store for later passing to a formatting
+   * function.
-    function.
+   *
-
+   * Note that custom types and string types (but not string views) are copied
-    Note that custom types and string types (but not string views) are copied
+   * into the store dynamically allocating memory if necessary.
-    into the store dynamically allocating memory if necessary.
+   *
-
+   * **Example**:
-    **Example**:
+   *
-
+   *     fmt::dynamic_format_arg_store<fmt::format_context> store;
-      fmt::dynamic_format_arg_store<fmt::format_context> store;
+   *     store.push_back(42);
-      store.push_back(42);
+   *     store.push_back("abc");
-      store.push_back("abc");
+   *     store.push_back(1.5f);
-      store.push_back(1.5f);
+   *     std::string result = fmt::vformat("{} and {} and {}", store);
-      std::string result = fmt::vformat("{} and {} and {}", store);
-    \endrst
    */
   template <typename T> void push_back(const T& arg) {
     if (detail::const_check(need_copy<T>::value))
@@ -176,19 +170,17 @@ class dynamic_format_arg_store
   }
 
   /**
-    \rst
+   * Adds a reference to the argument into the dynamic store for later passing
-    Adds a reference to the argument into the dynamic store for later passing to
+   * to a formatting function.
-    a formatting function.
+   *
-
+   * **Example**:
-    **Example**:
+   *
-
+   *     fmt::dynamic_format_arg_store<fmt::format_context> store;
-      fmt::dynamic_format_arg_store<fmt::format_context> store;
+   *     char band[] = "Rolling Stones";
-      char band[] = "Rolling Stones";
+   *     store.push_back(std::cref(band));
-      store.push_back(std::cref(band));
+   *     band[9] = 'c'; // Changing str affects the output.
-      band[9] = 'c'; // Changing str affects the output.
+   *     std::string result = fmt::vformat("{}", store);
-      std::string result = fmt::vformat("{}", store);
+   *     // result == "Rolling Scones"
-      // result == "Rolling Scones"
-    \endrst
    */
   template <typename T> void push_back(std::reference_wrapper<T> arg) {
     static_assert(
@@ -198,9 +190,9 @@ class dynamic_format_arg_store
   }
 
   /**
-    Adds named argument into the dynamic store for later passing to a formatting
+   * Adds named argument into the dynamic store for later passing to a
-    function. ``std::reference_wrapper`` is supported to avoid copying of the
+   * formatting function. `std::reference_wrapper` is supported to avoid
-    argument. The name is always copied into the store.
+   * copying of the argument. The name is always copied into the store.
    */
   template <typename T>
   void push_back(const detail::named_arg<char_type, T>& arg) {
@@ -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();
   }
 
-  /**
+  /// Reserves space to store at least `new_cap` arguments including
-    \rst
+  /// `new_cap_named` named arguments.
-    Reserves space to store at least `new_cap` arguments including
-    `new_cap_named` named arguments.
-    \endrst
-  */
   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");

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
-  A reference to a null-terminated string. It can be constructed from a C
+ * string or `std::string`.
-  string or ``std::string``.
+ *
-
+ * You can use one of the following type aliases for common character types:
-  You can use one of the following type aliases for common character types:
+ *
-
+ * +---------------+-----------------------------+
-  +---------------+-----------------------------+
+ * | Type          | Definition                  |
-  | Type          | Definition                  |
+ * +===============+=============================+
-  +===============+=============================+
+ * | cstring_view  | basic_cstring_view<char>    |
-  | cstring_view  | basic_cstring_view<char>    |
+ * +---------------+-----------------------------+
-  +---------------+-----------------------------+
+ * | wcstring_view | basic_cstring_view<wchar_t> |
-  | wcstring_view | basic_cstring_view<wchar_t> |
+ * +---------------+-----------------------------+
-  +---------------+-----------------------------+
+ *
-
+ * This class is most useful as a parameter type for functions that wrap C APIs.
-  This class is most useful as a parameter type to allow passing
-  different types of strings to a function, for example::
-
-    template <typename... Args>
-    std::string format(cstring_view format_str, const Args & ... args);
-
-    format("{}", 42);
-    format(std::string("{}"), 42);
-  \endrst
  */
 template <typename Char> 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) {}
 
-  /**
+  /// Constructs a string reference from an `std::string` object.
-    \rst
-    Constructs a string reference from an ``std::string`` object.
-    \endrst
-   */
   basic_cstring_view(const std::basic_string<Char>& 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 `std::system_error` object with the description of the form
- Constructs a :class:`std::system_error` object with the description
+ *
- of the form
+ *     <message>: <system-message>
-
+ *
- .. parsed-literal::
+ * where `<message>` is the formatted message and `<system-message>` is the
-   *<message>*: *<system-message>*
+ * system message corresponding to the error code.
-
+ * `error_code` is a Windows error code as given by `GetLastError`.
- where *<message>* is the formatted message and *<system-message>* is the
+ * If `error_code` is not a valid error code such as -1, the system message
- system message corresponding to the error code.
+ * will look like "error -1".
- `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
+ * **Example**:
- will look like "error -1".
+ *
-
+ *     // This throws a system_error with the description
- **Example**:
+ *     //   cannot open file 'madeup': The system cannot find the file
-
+ * specified.
-   // This throws a system_error with the description
+ *     // or similar (system message may vary).
-   //   cannot open file 'madeup': The system cannot find the file specified.
+ *     const char *filename = "madeup";
-   // or similar (system message may vary).
+ *     LPOFSTRUCT of = LPOFSTRUCT();
-   const char *filename = "madeup";
+ *     HFILE file = OpenFile(filename, &of, OF_READ);
-   LPOFSTRUCT of = LPOFSTRUCT();
+ *     if (file == HFILE_ERROR) {
-   HFILE file = OpenFile(filename, &of, OF_READ);
+ *       throw fmt::windows_error(GetLastError(),
-   if (file == HFILE_ERROR) {
+ *                                "cannot open file '{}'", filename);
-     throw fmt::windows_error(GetLastError(),
+ *     }
-                              "cannot open file '{}'", filename);
+ */
-   }
- \endrst
-*/
 template <typename... Args>
 std::system_error windows_error(int error_code, string_view message,
                                 const Args&... args) {
@@ -401,9 +385,7 @@ class file_buffer final : public buffer<char> {
 
 }  // namespace detail
 
-// Added {} below to work around default constructor error known to
+constexpr auto buffer_size = detail::buffer_size();
-// occur in Xcode versions 7.2.1 and 8.2.1.
-constexpr detail::buffer_size 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`:
-  Opens a file for writing. Supported parameters passed in `params`:
+ *
-
+ * - `<integer>`: Flags passed to [open](
-  * ``<integer>``: Flags passed to `open
+ *   https://pubs.opengroup.org/onlinepubs/007904875/functions/open.html)
-    <https://pubs.opengroup.org/onlinepubs/007904875/functions/open.html>`_
+ *   (`file::WRONLY | file::CREATE | file::TRUNC` by default)
-    (``file::WRONLY | file::CREATE | file::TRUNC`` by default)
+ * - `buffer_size=<integer>`: Output buffer size
-  * ``buffer_size=<integer>``: Output buffer size
+ *
-
+ * **Example**:
-  **Example**:
+ *
-
+ *     auto out = fmt::output_file("guide.txt");
-    auto out = fmt::output_file("guide.txt");
+ *     out.print("Don't {}", "Panic");
-    out.print("Don't {}", "Panic");
-  \endrst
  */
 template <typename... T>
 inline auto output_file(cstring_view path, T... params) -> ostream {

include/fmt/ostream.h

@@ -136,14 +136,12 @@ struct formatter<detail::streamed_view<T>, Char>
 };
 
 /**
-  \rst
+ * Returns a view that formats `value` via an ostream `operator<<`.
-  Returns a view that formats `value` via an ostream ``operator<<``.
+ *
-
+ * **Example**:
-  **Example**:
+ *
-
+ *     fmt::print("Current thread id: {}\n",
-    fmt::print("Current thread id: {}\n",
+ *                fmt::streamed(std::this_thread::get_id()));
-               fmt::streamed(std::this_thread::get_id()));
-  \endrst
  */
 template <typename T>
 constexpr auto streamed(const T& value) -> detail::streamed_view<T> {
@@ -172,13 +170,11 @@ void vprint(std::basic_ostream<Char>& os,
 }
 
 /**
-  \rst
+ * Prints formatted data to the stream `os`.
-  Prints formatted data to the stream `os`.
+ *
-
+ * **Example**:
-  **Example**:
+ *
-
+ *     fmt::print(cerr, "Don't {}!", "panic");
-    fmt::print(cerr, "Don't {}!", "panic");
-  \endrst
  */
 FMT_EXPORT template <typename... T>
 void print(std::ostream& os, format_string<T...> fmt, T&&... args) {

include/fmt/printf.h

@@ -36,12 +36,8 @@ template <typename Char> class basic_printf_context {
   using parse_context_type = basic_format_parse_context<Char>;
   template <typename T> using formatter_type = printf_formatter<T>;
 
-  /**
+  /// Constructs a `printf_context` object. References to the arguments are
-    \rst
+  /// stored in the context object so make sure they have appropriate lifetimes.
-    Constructs a ``printf_context`` object. References to the arguments are
-    stored in the context object so make sure they have appropriate lifetimes.
-    \endrst
-   */
   basic_printf_context(basic_appender<Char> out,
                        basic_format_args<basic_printf_context> args)
       : out_(out), args_(args) {}
@@ -227,7 +223,7 @@ auto make_arg_formatter(basic_appender<Char> iter, format_specs& s)
   return {iter, s, locale_ref()};
 }
 
-// The ``printf`` argument formatter.
+// The `printf` argument formatter.
 template <typename Char>
 class printf_arg_formatter : public arg_formatter<Char> {
  private:
@@ -276,7 +272,6 @@ class printf_arg_formatter : public arg_formatter<Char> {
     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<Char> {
       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<Char> {
 
   void operator()(basic_string_view<Char> 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<Char> {
       write_null_pointer();
   }
 
-  /** Formats an argument of a custom (user-defined) type. */
   void operator()(typename basic_format_arg<context_type>::handle handle) {
     auto parse_ctx = basic_format_parse_context<Char>({});
     handle.format(parse_ctx, context_);
@@ -573,12 +565,8 @@ using wprintf_context = basic_printf_context<wchar_t>;
 using printf_args = basic_format_args<printf_context>;
 using wprintf_args = basic_format_args<wprintf_context>;
 
-/**
+/// Constructs an `format_arg_store` object that contains references to
-  \rst
+/// arguments and can be implicitly converted to `printf_args`.
-  Constructs an `~fmt::format_arg_store` object that contains references to
-  arguments and can be implicitly converted to `~fmt::printf_args`.
-  \endrst
- */
 template <typename Char = char, typename... T>
 inline auto make_printf_args(T&... args)
     -> decltype(make_format_args<basic_printf_context<Char>>(args...)) {
@@ -599,14 +587,13 @@ inline auto vsprintf(basic_string_view<Char> fmt,
 }
 
 /**
-  \rst
+ * Formats `args` according to specifications in `fmt` and returns the result
-  Formats arguments and returns the result as a string.
+ * as as string.
-
+ *
-  **Example**:
+ * **Example**:
-
+ *
-    std::string message = fmt::sprintf("The answer is %d", 42);
+ *     std::string message = fmt::sprintf("The answer is %d", 42);
-  \endrst
+ */
-*/
 template <typename S, typename... T, typename Char = char_t<S>>
 inline auto sprintf(const S& fmt, const T&... args) -> std::basic_string<Char> {
   return vsprintf(detail::to_string_view(fmt),
@@ -625,13 +612,12 @@ inline auto vfprintf(std::FILE* f, basic_string_view<Char> fmt,
 }
 
 /**
-  \rst
+ * Formats `args` according to specifications in `fmt` and writes the output
-  Prints formatted data to the file `f`.
+ * to `f`.
-
+ *
-  **Example**:
+ * **Example**:
-
+ *
-    fmt::fprintf(stderr, "Don't %s!", "panic");
+ *     fmt::fprintf(stderr, "Don't %s!", "panic");
-  \endrst
  */
 template <typename S, typename... T, typename Char = char_t<S>>
 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<Char> fmt,
 }
 
 /**
-  \rst
+ * Formats `args` according to specifications in `fmt` and writes the output
-  Prints formatted data to ``stdout``.
+ * to `stdout`.
-
+ *
-  **Example**:
+ * **Example**:
-
+ *
-    fmt::printf("Elapsed time: %.2f seconds", 1.23);
+ *   fmt::printf("Elapsed time: %.2f seconds", 1.23);
-  \endrst
  */
 template <typename... T>
 inline auto printf(string_view fmt, const T&... args) -> int {