Adding user documentation for UseAuto transform

Reviewers: silvas, gribozavr
llvm-svn: 176735

2 files changed, 147 insertions, 0 deletions

diff --git a/clang-tools-extra/docs/UseAutoTransform.rst b/clang-tools-extra/docs/UseAutoTransform.rst
new file mode 100644
index 00000000000..53341a79167
--- /dev/null
+++ b/clang-tools-extra/docs/UseAutoTransform.rst
@@ -0,0 +1,137 @@
+.. 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-migrate`. 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
+variable type matches the type of the initializer expression. In other words
+``auto`` should deduce the same type that was originally spelled in the source.
+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 when all of the
+following conditions are satisfied:
+* The iterator is for one of the standard container in ``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 possible iterator types for standard containers:
+
+  * ``iterator``
+
+  * ``reverse_iterator``
+
+  * ``const_iterator``
+
+  * ``const_reverse_iterator``
+
+* In addition to using iterator types directly, typedefs or other ways of
+  referring to those types are also allowed. However, implementation-specific
+  types for which a type like ``std::vector<int>::iterator`` is itself a
+  typedef will not be transformed. Consider the following examples:
+
+.. code-block:: c++
+
+  // The following direct uses of iterator types will be transformed.
+  std::vector<int>::iterator I = MyVec.begin();
+  {
+    using namespace std;
+    list<int>::iterator I = MyList.begin();
+  }
+
+  // The type specifier for J would transform to auto since it's a typedef
+  // to a standard iterator type.
+  typedef std::map<int, std::string>::const_iterator map_iterator;
+  map_iterator J = MyMap.begin();
+
+  // The following implementation-specific iterator type for which
+  // std::vector<int>::iterator could be a typedef would not be transformed.
+  __gnu_cxx::__normal_iterator<int*, std::vector> K = MyVec.begin();
+
+* 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 as``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.
diff --git a/clang-tools-extra/docs/cpp11-migrate.rst b/clang-tools-extra/docs/cpp11-migrate.rst
index 55a5d4b99a7..48ad12b4191 100644
--- a/clang-tools-extra/docs/cpp11-migrate.rst
+++ b/clang-tools-extra/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 @@ Command Line Options
   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