Document the API using breathe.

doc/CMakeLists.txt

@@ -1,5 +1,6 @@
 add_custom_command(OUTPUT html/index.html
   COMMAND doxygen
+  COMMAND rm -rf ../html
   COMMAND sphinx-build -b html . ../html
   DEPENDS conf.py index.rst)
 add_custom_target(doc DEPENDS html/index.html)

doc/conf.py

@@ -23,6 +23,8 @@ import sys, os
 # If your documentation needs a minimal Sphinx version, state it here.
 #needs_sphinx = '1.0'
 
+sys.path.append("../breathe")
+
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = ['sphinx.ext.ifconfig', 'breathe']
@@ -52,9 +54,9 @@ copyright = u'1990-2012, Python Software Foundation'
 # built documents.
 #
 # The short X.Y version.
-version = '0.2'
+version = '0.3'
 # The full version, including alpha/beta/rc tags.
-release = '0.2'
+release = '0.3'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

doc/format.rst

@@ -1,39 +1,19 @@
 .. highlight:: c++
 
+.. _string-formatting:
+
+String Formatting
+-----------------
+
+.. doxygenfunction:: format::Format(StringRef)
+
+.. doxygenclass:: format::Formatter
+   :members:
+
 .. ifconfig:: False
 
-   .. _string-formatting:
-
-   String Formatting
-   -----------------
-
-   The built-in string class provides the ability to do complex variable
-   substitutions and value formatting via the :func:`format` method described in
-   :pep:`3101`.  The :class:`Formatter` class in the :mod:`format` module allows
-   you to create and customize your own string formatting behaviors using the same
-   implementation as the built-in :meth:`format` method.
-
-
    .. class:: Formatter
 
-      The :class:`Formatter` class has the following public methods:
-
-      .. method:: format(format_string, *args, **kwargs)
-
-         :meth:`format` is the primary API method.  It takes a format string and
-         an arbitrary set of positional and keyword arguments.
-         :meth:`format` is just a wrapper that calls :meth:`vformat`.
-
-      .. method:: vformat(format_string, args, kwargs)
-
-         This function does the actual work of formatting.  It is exposed as a
-         separate function for cases where you want to pass in a predefined
-         dictionary of arguments, rather than unpacking and repacking the
-         dictionary as individual arguments using the ``*args`` and ``**kwds``
-         syntax.  :meth:`vformat` does the work of breaking up the format string
-         into character data and replacement fields.  It calls the various
-         methods described below.
-
       In addition, the :class:`Formatter` defines a number of methods that are
       intended to be replaced by subclasses:
 
@@ -111,8 +91,8 @@
 Format String Syntax
 --------------------
 
-The :meth:`Format` function and the :class:`Formatter` class share the same
-syntax for format strings.
+The :cpp:func:`format::Format()` function and the :cpp:class:`format::Formatter`
+class share the same syntax for format strings.
 
 Format strings contain "replacement fields" surrounded by curly braces ``{}``.
 Anything that is not contained in braces is considered literal text, which is

format.h

@@ -183,12 +183,12 @@ class BasicFormatter {
 
 /**
   \rst
-  The :class:`Formatter` class provides string formatting
+  The :cpp:class:`format::Formatter` class provides string formatting
   functionality similar to Python's `str.format
   <http://docs.python.org/3/library/stdtypes.html#str.format>`__.
   The output is stored in a memory buffer that grows dynamically.
 
-  Usage::
+  **Example**::
 
      Formatter out;
      out("Current point:\n");
@@ -502,10 +502,15 @@ inline internal::ArgInserter Formatter::operator()(StringRef format) {
   return formatter;
 }
 
+// A formatting action that does nothing.
+struct NoAction {
+  void operator()(const Formatter &) const {}
+};
+
 // A formatter with an action performed when formatting is complete.
 // Objects of this class normally exist only as temporaries returned
 // by one of the formatting functions, thus the name.
-template <typename Action>
+template <typename Action = NoAction>
 class TempFormatter : public internal::ArgInserter {
  private:
   Formatter formatter_;
@@ -529,9 +534,9 @@ class TempFormatter : public internal::ArgInserter {
   // Action should be an unary function object that takes a const
   // reference to Formatter as an argument. See Ignore and Write
   // for examples of action classes.
-  explicit TempFormatter(const char *format, Action a = Action())
+  explicit TempFormatter(StringRef format, Action a = Action())
   : action_(a) {
-    Init(formatter_, format);
+    Init(formatter_, format.c_str());
   }
 
   TempFormatter(const Proxy &p)
@@ -551,16 +556,25 @@ class TempFormatter : public internal::ArgInserter {
   }
 };
 
-// A formatting action that does nothing.
-struct Ignore {
-  void operator()(const Formatter &) const {}
-};
+/**
+  \rst
+  Formats a string. Returns a temporary formatter object that accepts
+  arguments via operator ``<<``. *format* is a format string that contains
+  literal text and replacement fields surrounded by braces ``{}``.
+  The formatter object replaces the fields with formatted arguments
+  and stores the output in a memory buffer. The content of the buffer can
+  be converted to ``std::string`` with :meth:`str` or accessed as a C string
+  with :meth:`c_str`.
 
-// Formats a string.
-// Example:
-//   std::string s = str(Format("Elapsed time: {0:.2f} seconds") << 1.23);
-inline TempFormatter<Ignore> Format(const char *format) {
-  return TempFormatter<Ignore>(format);
+  **Example**::
+
+    std::string message = str(Format("Elapsed time: {0:.2f} seconds") << 1.23);
+
+  See also `Format String Syntax`_.
+  \endrst
+*/
+inline TempFormatter<> Format(StringRef format) {
+  return TempFormatter<>(format);
 }
 
 // A formatting action that writes formatted output to stdout.
@@ -573,7 +587,7 @@ struct Write {
 // Formats a string and prints it to stdout.
 // Example:
 //   Print("Elapsed time: {0:.2f} seconds") << 1.23;
-inline TempFormatter<Write> Print(const char *format) {
+inline TempFormatter<Write> Print(StringRef format) {
   return TempFormatter<Write>(format);
 }
 }

format_test.cc

@@ -995,8 +995,8 @@ TEST(TempFormatterTest, ActionNotCalledOnError) {
 TEST(TempFormatterTest, ArgLifetime) {
   // The following code is for testing purposes only. It is a definite abuse
   // of the API and shouldn't be used in real applications.
-  const fmt::TempFormatter<fmt::Ignore> &af = fmt::Format("{0}");
-  const_cast<fmt::TempFormatter<fmt::Ignore>&>(af) << std::string("test");
+  const fmt::TempFormatter<> &af = fmt::Format("{0}");
+  const_cast<fmt::TempFormatter<>&>(af) << std::string("test");
   // String object passed as an argument to TempFormatter has
   // been destroyed, but ArgInserter dtor hasn't been called yet.
   // But that's OK since the Arg's dtor takes care of this and