From 9e81263cf5b827eba900eb0ef1346ee7c3002e81 Mon Sep 17 00:00:00 2001
From: Victor Zverovich <victor.zverovich@gmail.com>
Date: Sat, 12 Jan 2013 10:08:39 -0800
Subject: [PATCH] Document the API.

---
 doc/conf.py    |  4 ++--
 doc/format.rst |  5 +++++
 format.h       | 29 +++++++++++++++++++++++------
 3 files changed, 30 insertions(+), 8 deletions(-)

diff --git a/doc/conf.py b/doc/conf.py
index cbd5512a..6c04afae 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -54,9 +54,9 @@ copyright = u'1990-2012, Python Software Foundation'
 # built documents.
 #
 # The short X.Y version.
-version = '0.3'
+version = '0.4'
 # The full version, including alpha/beta/rc tags.
-release = '0.3'
+release = '0.4'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
diff --git a/doc/format.rst b/doc/format.rst
index 0b3b16f7..442441a9 100644
--- a/doc/format.rst
+++ b/doc/format.rst
@@ -10,6 +10,11 @@ String Formatting
 .. doxygenclass:: format::Formatter
    :members:
 
+.. doxygenclass:: format::TempFormatter
+   :members:
+
+.. doxygenstruct:: format::NoAction
+
 .. doxygenclass:: format::StringRef
    :members:
 
diff --git a/format.h b/format.h
index ccb1285a..c1553707 100644
--- a/format.h
+++ b/format.h
@@ -761,8 +761,11 @@ inline internal::ArgInserter Formatter::operator()(StringRef format) {
   return formatter;
 }
 
-// A formatting action that does nothing.
+/**
+  A formatting action that does nothing.
+ */
 struct NoAction {
+  /** Does nothing. */
   void operator()(const Formatter &) const {}
 };
 
@@ -793,25 +796,39 @@ class TempFormatter : public internal::ArgInserter {
   };
 
  public:
-  // Creates an active formatter with a format string and an action.
-  // 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.
+  /**
+    \rst
+    Constructs a temporary formatter with a format string and an action.
+    The action should be an unary function object that takes a const
+    reference to :cpp:class:`format::Formatter` as an argument.
+    See :cpp:class:`format::NoAction` and :cpp:class:`format::Write` for
+    examples of action classes.
+    \endrst
+  */
   explicit TempFormatter(StringRef format, Action a = Action())
   : action_(a) {
     Init(formatter_, format.c_str());
   }
 
+  /**
+    Constructs a temporary formatter from a proxy object.
+   */
   TempFormatter(const Proxy &p)
   : ArgInserter(0), action_(p.action) {
     Init(formatter_, p.format);
   }
 
+  /**
+    Performs the actual formatting, invokes the action and destroys the object.
+   */
   ~TempFormatter() {
     if (formatter())
       action_(*Format());
   }
 
+  /**
+    Converts a temporary formatter into a proxy object.
+   */
   operator Proxy() {
     const char *fmt = format();
     ResetFormatter();
@@ -831,7 +848,7 @@ class TempFormatter : public internal::ArgInserter {
 
   **Example**::
 
-    std::string message = str(Format("Elapsed time: {0:.2f} seconds") << 1.23);
+    std::string message = str(Format("The answer is {}") << 42);
 
   See also `Format String Syntax`_.
   \endrst