From d130ee070f8ffcbe1628f138e6171780d45d6012 Mon Sep 17 00:00:00 2001
From: Victor Zverovich <viz@fb.com>
Date: Thu, 25 Jun 2020 06:57:23 -0700
Subject: [PATCH] Document format string compilation

---
 doc/api.rst           | 14 ++++++++++++++
 include/fmt/compile.h | 13 +++++++++++++
 include/fmt/format.h  |  2 +-
 3 files changed, 28 insertions(+), 1 deletion(-)

diff --git a/doc/api.rst b/doc/api.rst
index b93dba23..81db856c 100644
--- a/doc/api.rst
+++ b/doc/api.rst
@@ -14,6 +14,7 @@ The {fmt} library API consists of the following parts:
 * :ref:`fmt/ranges.h <ranges-api>`: additional formatting support for ranges
   and tuples
 * :ref:`fmt/chrono.h <chrono-api>`: date and time formatting
+* :ref:`fmt/compile.h <compile-api>`: format string compilation
 * :ref:`fmt/ostream.h <ostream-api>`: ``std::ostream`` support
 * :ref:`fmt/printf.h <printf-api>`: ``printf`` formatting
 
@@ -421,6 +422,19 @@ formatting::
 The format string syntax is described in the documentation of
 `strftime <http://en.cppreference.com/w/cpp/chrono/c/strftime>`_.
 
+.. _compile-api:
+
+Format string compilation
+=========================
+
+Format strings can be processed at compile time for built-in and string types
+as well as user-defined types with ``constexpr`` ``parse`` functions in their
+``formatter`` specializations. Format string compilation can generate more
+binary code compared to the normal API and is only recommended in places where
+formatting is a performance bottleneck.
+
+.. doxygendefine:: FMT_COMPILE
+
 .. _ostream-api:
 
 ``std::ostream`` Support
diff --git a/include/fmt/compile.h b/include/fmt/compile.h
index 67f7a7f7..6c083e7d 100644
--- a/include/fmt/compile.h
+++ b/include/fmt/compile.h
@@ -21,6 +21,19 @@ class compiled_string {};
 template <typename S>
 struct is_compiled_string : std::is_base_of<compiled_string, S> {};
 
+/**
+  \rst
+  Constructs a format string that will be translated into an efficient
+  formatting code at compile time from a string literal *s*. Requires C++17
+  ``constexpr if``.
+
+  **Example**::
+
+    // Converts 42 into std::string using the most efficient code and no runtime
+    // format string processing.
+    std::string s = fmt::format(FMT_COMPILE("{}"), 42);
+  \endrst
+ */
 #define FMT_COMPILE(s) FMT_STRING_IMPL(s, fmt::detail::compiled_string)
 
 template <typename T, typename... Tail>
diff --git a/include/fmt/format.h b/include/fmt/format.h
index 646aa2f7..2d1ee89f 100644
--- a/include/fmt/format.h
+++ b/include/fmt/format.h
@@ -2840,7 +2840,7 @@ FMT_CONSTEXPR basic_string_view<Char> compile_string_to_view(
   **Example**::
 
     // A compile-time error because 'd' is an invalid specifier for strings.
-    std::string s = format(FMT_STRING("{:d}"), "foo");
+    std::string s = fmt::format(FMT_STRING("{:d}"), "foo");
   \endrst
  */
 #define FMT_STRING(s) FMT_STRING_IMPL(s, fmt::compile_string)