Update docs

doc/api.rst

@@ -4,14 +4,29 @@
 API Reference
 *************
 
-All functions and classes provided by the {fmt} library reside in namespace
-``fmt`` and macros have prefix ``FMT_``.
+The {fmt} library API consists of the following parts:
 
-Format API
-==========
+* :ref:`fmt/core.h <core-api>`: the core API providing argument handling
+  facilities and a lightweight subset of formatting functions
+* :ref:`fmt/format.h <format-api>`: the full format API providing compile-time
+  format string checks, output iterator and user-defined type support
+* :ref:`fmt/time.h <time-api>`: date and time formatting
+* :ref:`fmt/ostream.h <ostream-api>`: ``std::ostream`` support
+* :ref:`fmt/printf.h <printf-api>`: ``printf`` formatting
+
+All functions and types provided by the library reside in namespace ``fmt`` and
+macros have prefix ``FMT_`` or ``fmt``.
+
+.. _core-api:
+
+Core API
+========
+
+``fmt/core.h`` defines the core API which provides argument handling facilities
+and a lightweight subset of formatting functions.
 
-The following functions defined in ``fmt/core.h`` use :ref:`format string
-syntax <syntax>` similar to that of Python's `str.format
+The following functions use :ref:`format string syntax <syntax>`
+imilar to that of Python's `str.format
 <http://docs.python.org/3/library/stdtypes.html#str.format>`_.
 They take *format_str* and *args* as arguments.
 
@@ -21,35 +36,52 @@ arguments in the resulting string.
 
 *args* is an argument list representing objects to be formatted.
 
-The `performance of the formating functions
-<https://github.com/fmtlib/fmt/blob/master/README.rst#speed-tests>`_ is close
-to that of glibc's ``printf`` and better than the performance of IOStreams.
-
 .. _format:
 
 .. doxygenfunction:: format(string_view, const Args&...)
+.. doxygenfunction:: vformat(string_view, format_args)
 
 .. _print:
 
 .. doxygenfunction:: print(string_view, const Args&...)
+.. doxygenfunction:: vprint(string_view, format_args)
 
 .. doxygenfunction:: print(std::FILE *, string_view, const Args&...)
+.. doxygenfunction:: vprint(std::FILE *, string_view, format_args)
 
-Date and time formatting
-------------------------
+.. _format-api:
 
-The library supports `strftime
-<http://en.cppreference.com/w/cpp/chrono/c/strftime>`_-like date and time
-formatting::
+Named arguments
+---------------
+
+.. doxygenfunction:: fmt::arg(string_view, const T&)
 
-  #include "fmt/time.h"
+Argument lists
+--------------
 
-  std::time_t t = std::time(nullptr);
-  // Prints "The date is 2016-04-29." (with the current date)
-  fmt::print("The date is {:%Y-%m-%d}.", *std::localtime(&t));
+.. doxygenclass:: fmt::basic_format_args
+   :members:
 
-The format string syntax is described in the documentation of
-`strftime <http://en.cppreference.com/w/cpp/chrono/c/strftime>`_.
+.. doxygenstruct:: fmt::format_args
+
+.. doxygenfunction:: fmt::make_args(const Args&...)
+
+Compatibility
+-------------
+
+.. doxygenclass:: fmt::basic_string_view
+   :members:
+
+Format API
+==========
+
+``fmt/format.h`` defines the full format API providing compile-time format
+string checks, output iterator and user-defined type support.
+
+Compile-time format string checks
+---------------------------------
+
+.. doxygendefine:: fmt
 
 Formatting user-defined types
 -----------------------------
@@ -57,6 +89,8 @@ Formatting user-defined types
 To make a user-defined type formattable, specialize the ``formatter<T>`` struct
 template and implement ``parse`` and ``format`` methods::
 
+  #include <fmt/format.h>
+
   struct point { double x, y; };
 
   namespace fmt {
@@ -88,38 +122,71 @@ This section shows how to define a custom format function for a user-defined
 type. The next section describes how to get ``fmt`` to use a conventional stream
 output ``operator<<`` when one is defined for a user-defined type.
 
-``std::ostream`` support
-------------------------
+Output iterator support
+-----------------------
 
-The header ``fmt/ostream.h`` provides ``std::ostream`` support including
-formatting of user-defined types that have overloaded ``operator<<``::
+.. doxygenfunction:: fmt::format_to(OutputIt, string_view, const Args&...)
 
-  #include "fmt/ostream.h"
+Literal-based API
+-----------------
 
-  class date {
-    int year_, month_, day_;
-  public:
-    date(int year, int month, int day): year_(year), month_(month), day_(day) {}
+The following user-defined literals are defined in ``fmt/format.h``.
 
-    friend std::ostream &operator<<(std::ostream &os, const date &d) {
-      return os << d.year_ << '-' << d.month_ << '-' << d.day_;
-    }
-  };
+.. doxygenfunction:: operator""_format(const char *, std::size_t)
 
-  std::string s = fmt::format("The date is {}", date(2012, 12, 9));
-  // s == "The date is 2012-12-9"
+.. doxygenfunction:: operator""_a(const char *, std::size_t)
 
-.. doxygenfunction:: print(std::ostream&, string_view, const Args&...)
+Utilities
+---------
 
-Literal-based API
+.. doxygenfunction:: fmt::to_string(const T&)
+
+.. doxygenclass:: fmt::basic_memory_buffer
+   :protected-members:
+   :members:
+
+System errors
+-------------
+
+.. doxygenclass:: fmt::system_error
+   :members:
+
+.. doxygenfunction:: fmt::format_system_error
+
+.. doxygenclass:: fmt::windows_error
+   :members:
+
+.. _formatstrings:
+
+Custom allocators
 -----------------
 
-The following user-defined literals are defined in ``fmt/format.h``.
+The {fmt} library supports custom dynamic memory allocators.
+A custom allocator class can be specified as a template argument to
+:class:`fmt::basic_memory_buffer`::
 
-.. doxygenfunction:: operator""_format(const char *, std::size_t)
+    using custom_memory_buffer = 
+      fmt::basic_memory_buffer<char, fmt::inline_buffer_size, custom_allocator>;
 
-.. doxygenfunction:: operator""_a(const char *, std::size_t)
+It is also possible to write a formatting function that uses a custom
+allocator::
+
+    using custom_string =
+      std::basic_string<char, std::char_traits<char>, custom_allocator>;
 
+    custom_string vformat(custom_allocator alloc, fmt::string_view format_str,
+                          fmt::format_args args) {
+      custom_memory_buffer buf(alloc);
+      fmt::vformat_to(buf, format_str, args);
+      return custom_string(buf.data(), buf.size(), alloc);
+    }
+
+    template <typename ...Args>
+    inline custom_string format(custom_allocator alloc,
+                                fmt::string_view format_str,
+                                const Args & ... args) {
+      return vformat(alloc, format_str, fmt::make_args(args...));
+    }
 Custom formatting of built-in types
 -----------------------------------
 
@@ -170,8 +237,53 @@ custom argument formatter class::
 .. doxygenclass:: fmt::arg_formatter
    :members:
 
-Printf formatting
------------------
+.. _time-api:
+
+Date and time formatting
+========================
+
+The library supports `strftime
+<http://en.cppreference.com/w/cpp/chrono/c/strftime>`_-like date and time
+formatting::
+
+  #include <fmt/time.h>
+
+  std::time_t t = std::time(nullptr);
+  // Prints "The date is 2016-04-29." (with the current date)
+  fmt::print("The date is {:%Y-%m-%d}.", *std::localtime(&t));
+
+The format string syntax is described in the documentation of
+`strftime <http://en.cppreference.com/w/cpp/chrono/c/strftime>`_.
+
+.. _ostream-api:
+
+``std::ostream`` support
+========================
+
+``fmt/ostream.h`` provides ``std::ostream`` support including formatting of
+user-defined types that have overloaded ``operator<<``::
+
+  #include <fmt/ostream.h>
+
+  class date {
+    int year_, month_, day_;
+  public:
+    date(int year, int month, int day): year_(year), month_(month), day_(day) {}
+
+    friend std::ostream &operator<<(std::ostream &os, const date &d) {
+      return os << d.year_ << '-' << d.month_ << '-' << d.day_;
+    }
+  };
+
+  std::string s = fmt::format("The date is {}", date(2012, 12, 9));
+  // s == "The date is 2012-12-9"
+
+.. doxygenfunction:: print(std::ostream&, string_view, const Args&...)
+
+.. _printf-api:
+
+``printf`` formatting
+=====================
 
 The header ``fmt/printf.h`` provides ``printf``-like formatting functionality.
 The following functions use `printf format string syntax
@@ -220,62 +332,3 @@ store output elsewhere by subclassing `~fmt::BasicWriter`.
 
 .. doxygenfunction:: pad(int, unsigned, Char)
 
-Utilities
-=========
-
-.. doxygenfunction:: fmt::arg(string_view, const T&)
-
-.. doxygenclass:: fmt::basic_format_args
-   :members:
-
-.. doxygenfunction:: fmt::to_string(const T&)
-
-.. doxygenclass:: fmt::basic_string_view
-   :members:
-
-.. doxygenclass:: fmt::basic_memory_buffer
-   :protected-members:
-   :members:
-
-System errors
-=============
-
-.. doxygenclass:: fmt::system_error
-   :members:
-
-.. doxygenfunction:: fmt::format_system_error
-
-.. doxygenclass:: fmt::windows_error
-   :members:
-
-.. _formatstrings:
-
-Custom allocators
-=================
-
-The {fmt} library supports custom dynamic memory allocators.
-A custom allocator class can be specified as a template argument to
-:class:`fmt::basic_memory_buffer`::
-
-    using custom_memory_buffer = 
-      fmt::basic_memory_buffer<char, fmt::inline_buffer_size, custom_allocator>;
-
-It is also possible to write a formatting function that uses a custom
-allocator::
-
-    using custom_string =
-      std::basic_string<char, std::char_traits<char>, custom_allocator>;
-
-    custom_string vformat(custom_allocator alloc, fmt::string_view format_str,
-                          fmt::format_args args) {
-      custom_memory_buffer buf(alloc);
-      fmt::vformat_to(buf, format_str, args);
-      return custom_string(buf.data(), buf.size(), alloc);
-    }
-
-    template <typename ...Args>
-    inline custom_string format(custom_allocator alloc,
-                                fmt::string_view format_str,
-                                const Args & ... args) {
-      return vformat(alloc, format_str, fmt::make_args(args...));
-    }

include/fmt/core.h

@@ -1069,7 +1069,8 @@ class basic_format_args {
   }
 };
 
-// This is a separate type rather than a typedef to make symbols readable.
+/** An alias to ``basic_format_args<context>``. */
+// It is a separate type rather than a typedef to make symbols readable.
 struct format_args: basic_format_args<context> {
   template <typename ...Args>
   format_args(Args && ... arg)
@@ -1179,7 +1180,7 @@ std::wstring vformat(wstring_view format_str, wformat_args args);
 
   **Example**::
 
-    #include "fmt/core.h"
+    #include <fmt/core.h>
     std::string message = fmt::format("The answer is {}", 42);
   \endrst
 */

include/fmt/format.h

@@ -3315,7 +3315,7 @@ auto join(const Range &range, wstring_view sep)
 
   **Example**::
 
-    #include "fmt/format.h"
+    #include <fmt/format.h>
 
     std::string answer = fmt::to_string(42);
   \endrst
@@ -3528,6 +3528,16 @@ operator"" _a(const wchar_t *s, std::size_t) { return {s}; }
   }()
 
 #ifndef FMT_NO_FMT_STRING_ALIAS
+/**
+  \rst
+  Constructs a compile-time format string.
+
+  **Example**::
+
+    #include <fmt/format.h>
+    std::string s = fmt::format(fmt("{:d}"), "foo"); // fails to compile
+  \endrst
+ */
 # define fmt(s) FMT_STRING(s)
 #endif