[PATCH] Adding user documentation for UseAuto transform

[Edwin Vane]

Hi silvas, klimek, gribozavr,

I will be shortly moving all transform information into separate pages. This
UseAuto transform doc is setting the precedent.

http://llvm-reviews.chandlerc.com/D508

Files:
  docs/UseAutoTransform.rst
  docs/cpp11-migrate.rst

Index: docs/UseAutoTransform.rst
===================================================================
--- /dev/null
+++ docs/UseAutoTransform.rst
@@ -0,0 +1,130 @@
+.. index:: Loop Convert Transform
+
+==================
+Use-Auto Transform
+==================
+
+The Use-Auto Transform is responsible for using the ``auto`` type specifier for
+variable declarations to *improve code readability and maintainability*. The
+transform is enabled with the :option:`-loop-convert` option of
+:program:`cpp11-migrage`. For example:
+
+.. code-block:: c++
+
+  std::vector<int>::iterator I = my_container.begin();
+
+  // transforms to:
+
+  auto I = my_container.begin();
+
+The ``auto`` type specifier will only be introduced in situations where the
+type specifier of the variable declaration matches the type of the initializer
+expression. However, not every situation should be transformed:
+
+.. code-block:: c++
+
+  int val = 42;
+  InfoStruct &I = SomeObject.getInfo();
+
+  // Should not become:
+
+  auto val = 42;
+  auto &I = SomeObject.getInfo();
+
+In this example using ``auto`` for builtins doesn't improve readability. In
+other situations it makes the code less self-documenting impairing readability
+and maintainability. As a result, ``auto`` is used only introduced in specific
+situations described below.
+
+Iterators
+=========
+
+Iterator type specifiers tend to be long and used frequently, especially in
+loop constructs. Since the functions generating iterators have a common format,
+the type specifier can be replaced without obscuring the meaning of code while 
+improving readability and maintainability.
+
+.. code-block:: c++
+
+  for (std::vector<int>::iterator I = my_container.begin(),
+                                  E = my_container.end();
+       I != E; ++I) {
+  }
+
+  // becomes
+
+  for (auto I = my_container.begin(), E = my_container.end(); I != E; ++I) {
+  }
+
+The transform will only replace iterator type-specifiers in the following
+situations:
+* The iterator is for one of the C++ Specification-defined containers from the ``std`` namespace:
+
+  * ``array``
+
+  * ``deque``
+
+  * ``forward_list``
+
+  * ``list``
+
+  * ``vector``
+
+  * ``map``
+
+  * ``multimap``
+
+  * ``set``
+
+  * ``multiset``
+
+  * ``unordered_map``
+
+  * ``unordered_multimap``
+
+  * ``unordered_set``
+
+  * ``unordered_multiset``
+
+  * ``queue``
+
+  * ``priority_queue``
+
+  * ``stack``
+
+* The iterator is one of the specification-defined iterator types:
+
+  * ``iterator``
+
+  * ``reverse_iterator``
+
+  * ``const_iterator``
+
+  * ``const_reverse_iterator``
+
+* The type specifier uses no less *type sugar* than the type specifiers given
+  in the specification. Consider the following examples:
+
+.. code-block:: c++
+
+  // Type specifier allowed by specification.
+  std::vector<int>::iterator I;
+
+  // More type sugar is ok.
+  typedef std::map<int, std::string>::const_iterator map_iterator;
+  map_iterator J;
+
+  // The following implementation-specific iterator type for which
+  // std::vector<int>::iterator is a more sugared type specifier is not
+  // transformed.
+  __gnu_cxx::__normal_iterator<int*, std::vector> K;
+
+* The initializer for the variable being declared is not a braced initializer
+  list. Otherwise, use of ``auto`` would cause the type of the variable to be
+  deduced to ``std::initializer_list``.
+
+Known Limitations
+-----------------
+* If the initializer is an explicit conversion constructor, the transform will
+  not replace the type specifier even though it would be safe to do so.
+* User-defined iterators are not handled at this time.
Index: docs/cpp11-migrate.rst
===================================================================
--- docs/cpp11-migrate.rst
+++ docs/cpp11-migrate.rst
@@ -2,6 +2,11 @@
 cpp11-migrate User's Manual
 ===========================
 
+.. toctree::
+   :hidden:
+
+   UseAutoTransform
+
 :program:`cpp11-migrate` is a standalone tool used to automatically convert
 C++98 and C++03 code to use features of the new C++11 standard where
 appropriate.
@@ -30,6 +35,11 @@
   Makes use of C++11 range-based for loops where possible.
   See :ref:`loop-convert-transformation`.
 
+.. option:: -use-auto
+
+  Replace the type specifier of variable declarations with the ``auto`` type
+  specifier. See :doc:`UseAutoTransform`.
+
 .. option:: -p=<build-path>
 
   ``<build-path>`` is a CMake build directory containing a file named
-------------- next part --------------
A non-text attachment was scrubbed...
Name: D508.1.patch
Type: text/x-patch
Size: 4449 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/cfe-commits/attachments/20130308/644b258a/attachment.bin>