Make format_to return iterator and update docs

doc/api.rst

@@ -4,9 +4,8 @@
 API Reference
 *************
 
-All functions and classes provided by the fmt library reside in namespace
-``fmt`` and macros have prefix ``FMT_``. For brevity the namespace is usually
-omitted in examples.
+All functions and classes provided by the {fmt} library reside in namespace
+``fmt`` and macros have prefix ``FMT_``.
 
 Format API
 ==========
@@ -60,28 +59,28 @@ Formatting user-defined types
 To make a user-defined type formattable, specialize the ``formatter<T>`` struct
 template and implement ``parse`` and ``format`` methods::
 
-  struct MyStruct { double x, y; };
+  struct point { double x, y; };
 
   namespace fmt {
   template <>
-  struct formatter<MyStruct> {
+  struct formatter<point> {
     template <typename ParseContext>
     auto parse(ParseContext &ctx) { return ctx.begin(); }
 
     template <typename FormatContext>
-    auto format(const MyStruct &s, FormatContext &ctx) {
-      return format_to(ctx.begin(), "[MyStruct: x={:.1f}, y={:.2f}]", s.x, s.y);
+    auto format(const point &p, FormatContext &ctx) {
+      return format_to(ctx.begin(), "({:.1f}, {:.1f})", p.x, p.y);
     }
   };
   }
 
-Then you can pass objects of type ``MyStruct`` to any formatting function::
+Then you can pass objects of type ``point`` to any formatting function::
 
-  MyStruct m = {1, 2};
-  std::string s = fmt::format("m={}", m);
-  // s == "m=[MyStruct: x=1.0, y=2.00]"
+  point p = {1, 2};
+  std::string s = fmt::format("{}", p);
+  // s == "(1.0, 2.0)"
 
-In the example above the ``formatter<MyStruct>::parse`` function ignores the
+In the example above the ``formatter<point>::parse`` function ignores the
 contents of the format string referred to by ``ctx.begin()`` so the object will
 always be formatted in the same way. See ``formatter<tm>::parse`` in
 :file:`fmt/time.h` for an advanced example of how to parse the format string and