Switch to markdown

include/fmt/base.h

@@ -1817,10 +1817,8 @@ FMT_DEPRECATED FMT_CONSTEXPR auto visit_format_arg(
  * should only be used as a parameter type in type-erased functions such as
  * `vformat`:
  *
- * ```
+ *     void vlog(string_view format_str, format_args args);  // OK
- * void vlog(string_view format_str, format_args args);  // OK
+ *     format_args args = make_format_args();  // Error: dangling reference
- * format_args args = make_format_args();  // Error: dangling reference
- * ```
  */
 template <typename Context> class basic_format_args {
  public:
@@ -1956,7 +1954,7 @@ class context {
   // Returns an iterator to the beginning of the output range.
   FMT_CONSTEXPR auto out() -> iterator { return out_; }
 
-  // Advances the begin iterator to ``it``.
+  // Advances the begin iterator to `it`.
   void advance_to(iterator) {}
 
   FMT_CONSTEXPR auto locale() -> detail::locale_ref { return loc_; }
@@ -1985,12 +1983,9 @@ concept formattable = is_formattable<remove_reference_t<T>, Char>::value;
 #endif
 
 /**
-  \rst
+ * Constructs an object that stores references to arguments and can be
-  Constructs an object that stores references to arguments and can be implicitly
+ * implicitly converted to `format_args`. `Context` can be omitted in which case
-  converted to `~fmt::format_args`. `Context` can be omitted in which case it
+ * it defaults to `format_context`. See `arg` for lifetime considerations.
-  defaults to `~fmt::format_context`. See `~fmt::arg` for lifetime
-  considerations.
-  \endrst
  */
 // Take arguments by lvalue references to avoid some lifetime issues, e.g.
 //   auto args = make_format_args(std::string());
@@ -2019,13 +2014,13 @@ constexpr auto make_format_args(T&... args)
 #endif
 
 /**
-  Returns a named argument to be used in a formatting function.
+ * Returns a named argument to be used in a formatting function.
-  It should only be used in a call to a formatting function or
+ * It should only be used in a call to a formatting function or
-  `dynamic_format_arg_store::push_back`.
+ * `dynamic_format_arg_store::push_back`.
-
+ *
-  **Example**::
+ * **Example**:
-
+ *
-    fmt::print("Elapsed time: {s:.2f} seconds", fmt::arg("s", 1.23));
+ *     fmt::print("Elapsed time: {s:.2f} seconds", fmt::arg("s", 1.23));
  */
 template <typename Char, typename T>
 inline auto arg(const Char* name, const T& arg) -> detail::named_arg<Char, T> {
@@ -2882,14 +2877,12 @@ inline auto runtime(string_view s) -> string_view { return s; }
 template <typename... Args>
 using format_string = basic_format_string<char, type_identity_t<Args>...>;
 /**
-  \rst
+ * Creates a runtime format string.
-  Creates a runtime format string.
+ *
-
+ * **Example**:
-  **Example**::
+ *
-
+ *     // Check format string at runtime instead of compile-time.
-    // Check format string at runtime instead of compile-time.
+ *     fmt::print(fmt::runtime("{:d}"), "I am not a number");
-    fmt::print(fmt::runtime("{:d}"), "I am not a number");
-  \endrst
  */
 inline auto runtime(string_view s) -> runtime_format_string<> { return {{s}}; }
 #endif
@@ -2906,16 +2899,14 @@ auto vformat_to(OutputIt&& out, string_view fmt, format_args args)
 }
 
 /**
- \rst
+ * Formats `args` according to specifications in `fmt`, writes the result to
- Formats ``args`` according to specifications in ``fmt``, writes the result to
+ * the output iterator `out` and returns the iterator past the end of the output
- the output iterator ``out`` and returns the iterator past the end of the output
+ * range. `format_to` does not append a terminating null character.
- range. `format_to` does not append a terminating null character.
+ *
-
+ * **Example**:
- **Example**::
+ *
-
+ *    auto out = std::vector<char>();
-   auto out = std::vector<char>();
+ *    fmt::format_to(std::back_inserter(out), "{}", 42);
-   fmt::format_to(std::back_inserter(out), "{}", 42);
- \endrst
  */
 template <typename OutputIt, typename... T,
           FMT_ENABLE_IF(detail::is_output_iterator<remove_cvref_t<OutputIt>,
@@ -2926,9 +2917,9 @@ FMT_INLINE auto format_to(OutputIt&& out, format_string<T...> fmt, T&&... args)
 }
 
 template <typename OutputIt> struct format_to_n_result {
-  /** Iterator past the end of the output range. */
+  /// Iterator past the end of the output range.
   OutputIt out;
-  /** Total (not truncated) output size. */
+  /// Total (not truncated) output size.
   size_t size;
 };
 
@@ -2943,12 +2934,10 @@ auto vformat_to_n(OutputIt out, size_t n, string_view fmt, format_args args)
 }
 
 /**
-  \rst
+ * Formats `args` according to specifications in `fmt`, writes up to `n`
-  Formats ``args`` according to specifications in ``fmt``, writes up to ``n``
+ * characters of the result to the output iterator `out` and returns the total
-  characters of the result to the output iterator ``out`` and returns the total
+ * (not truncated) output size and the iterator past the end of the output
-  (not truncated) output size and the iterator past the end of the output range.
+ * range. `format_to_n` does not append a terminating null character.
-  `format_to_n` does not append a terminating null character.
-  \endrst
  */
 template <typename OutputIt, typename... T,
           FMT_ENABLE_IF(detail::is_output_iterator<OutputIt, char>::value)>
@@ -2959,9 +2948,9 @@ FMT_INLINE auto format_to_n(OutputIt out, size_t n, format_string<T...> fmt,
 
 template <typename OutputIt, typename Sentinel = OutputIt>
 struct format_to_result {
-  /** Iterator pointing to just after the last successful write in the range. */
+  /// Iterator pointing to just after the last successful write in the range.
   OutputIt out;
-  /** Specifies if the output was truncated. */
+  /// Specifies if the output was truncated.
   bool truncated;
 
   FMT_CONSTEXPR operator OutputIt&() & noexcept { return out; }
@@ -2985,7 +2974,7 @@ FMT_INLINE auto format_to(char (&out)[N], format_string<T...> fmt, T&&... args)
   return {result.out, result.size > N};
 }
 
-/** Returns the number of chars in the output of ``format(fmt, args...)``. */
+/// Returns the number of chars in the output of `format(fmt, args...)`.
 template <typename... T>
 FMT_NODISCARD FMT_INLINE auto formatted_size(format_string<T...> fmt,
                                              T&&... args) -> size_t {
@@ -3004,9 +2993,8 @@ FMT_API void vprintln(FILE* f, string_view fmt, format_args args);
  * to `stdout`.
  *
  * **Example**:
- * ```
+ * 
- * fmt::print("Elapsed time: {0:.2f} seconds", 1.23);
+ *     fmt::print("Elapsed time: {0:.2f} seconds", 1.23);
- * ```
  */
 template <typename... T>
 FMT_INLINE void print(format_string<T...> fmt, T&&... args) {
@@ -3032,10 +3020,8 @@ FMT_INLINE void print(FILE* f, format_string<T...> fmt, T&&... args) {
                                     : vprint(f, fmt, vargs);
 }
 
-/**
+/// Formats `args` according to specifications in `fmt` and writes the output
-  Formats ``args`` according to specifications in ``fmt`` and writes the
+/// to the file `f` followed by a newline.
-  output to the file ``f`` followed by a newline.
- */
 template <typename... T>
 FMT_INLINE void println(FILE* f, format_string<T...> fmt, T&&... args) {
   const auto& vargs = fmt::make_format_args(args...);
@@ -3043,10 +3029,8 @@ FMT_INLINE void println(FILE* f, format_string<T...> fmt, T&&... args) {
                             : detail::vprint_mojibake(f, fmt, vargs, true);
 }
 
-/**
+/// Formats `args` according to specifications in `fmt` and writes the output
-  Formats ``args`` according to specifications in ``fmt`` and writes the output
+/// to `stdout` followed by a newline.
-  to ``stdout`` followed by a newline.
- */
 template <typename... T>
 FMT_INLINE void println(format_string<T...> fmt, T&&... args) {
   return fmt::println(stdout, fmt, static_cast<T&&>(args)...);