Improve docs

README.rst

@@ -145,29 +145,6 @@ Write a file from a single thread:
 
 This is up to 6x faster than glibc's ``fprintf``.
 
-Create your own functions similar to `format
-<https://fmt.dev/latest/api.html#format>`_ and
-`print <https://fmt.dev/latest/api.html#print>`_
-which take arbitrary arguments (`godbolt <https://godbolt.org/g/MHjHVf>`_):
-
-.. code:: c++
-
-    // Prints formatted error message.
-    void vreport_error(const char* format, fmt::format_args args) {
-      fmt::print("Error: ");
-      fmt::vprint(format, args);
-    }
-    template <typename... Args>
-    void report_error(const char* format, const Args & ... args) {
-      vreport_error(format, fmt::make_format_args(args...));
-    }
-
-    report_error("file not found: {}", path);
-
-Note that ``vreport_error`` is not parameterized on argument types which can
-improve compile times and reduce code size compared to a fully parameterized
-version.
-
 Benchmarks
 ----------
 

doc/api.rst

@@ -66,6 +66,33 @@ Named arguments are not supported in compile-time checks at the moment.
 Argument Lists
 --------------
 
+You can create your own formatting function with compile-time checks and small
+binary footprint, for example (https://godbolt.org/z/oba4Mc):
+
+.. code:: c++
+
+    #include <fmt/format.h>
+
+    void vlog(const char* file, int line, fmt::string_view format,
+              fmt::format_args args) {
+      fmt::print("{}: {}: ", file, line);
+      fmt::vprint(format, args);
+    }
+
+    template <typename S, typename... Args>
+    void log(const char* file, int line, const S& format, Args&&... args) {
+      vlog(file, line, format,
+          fmt::make_args_checked<Args...>(format, args...));
+    }
+
+    #define MY_LOG(format, ...) \
+      log(__FILE__, __LINE__, FMT_STRING(format), __VA_ARGS__)
+
+    MY_LOG("invalid squishiness: {}", 42);
+
+Note that ``vlog`` is not parameterized on argument types which improves compile
+times and reduces binary code size compared to a fully parameterized version.
+
 .. doxygenfunction:: fmt::make_format_args(const Args&...)
 
 .. doxygenfunction:: fmt::make_args_checked(const S&, const remove_reference_t<Args>&...)

include/fmt/color.h

@@ -504,11 +504,15 @@ void vprint(std::FILE* f, const text_style& ts, const S& format,
 }
 
 /**
+  \rst
   Formats a string and prints it to the specified file stream using ANSI
   escape sequences to specify text formatting.
-  Example:
+
+  **Example**::
+
     fmt::print(fmt::emphasis::bold | fg(fmt::color::red),
                "Elapsed time: {0:.2f} seconds", 1.23);
+  \endrst
  */
 template <typename S, typename... Args,
           FMT_ENABLE_IF(detail::is_string<S>::value)>

include/fmt/core.h

@@ -1567,11 +1567,18 @@ inline format_arg_store<Context, Args...> make_format_args(
   return {args...};
 }
 
-/** Same as `make_format_args` but with compile-time format string checks. */
+/**
+  \rst
+  Constructs an `~fmt::format_arg_store` object that contains references
+  to arguments and can be implicitly converted to `~fmt::format_args`.
+  If ``format_str`` is a compile-time string then `make_args_checked` checks
+  its validity at compile time.
+  \endrst
+ */
 template <typename... Args, typename S, typename Char = char_t<S>>
-inline format_arg_store<buffer_context<Char>, remove_reference_t<Args>...>
-make_args_checked(const S& format_str,
-                  const remove_reference_t<Args>&... args) {
+inline auto make_args_checked(const S& format_str,
+                              const remove_reference_t<Args>&... args)
+    -> format_arg_store<buffer_context<Char>, remove_reference_t<Args>...> {
   static_assert(
       detail::count<(
               std::is_base_of<detail::view, remove_reference_t<Args>>::value &&