Splitting cpp11-migrate transform docs into sub-pages

Each transform belongs in its own sub-page now. Minor refactoring to reflect
new heading levels.

llvm-svn: 176757

clang-tools-extra/docs/LoopConvertTransform.rst

@@ -0,0 +1,120 @@
+.. index:: Loop Convert Transform
+
+======================
+Loop Convert Transform
+======================
+
+The Loop Convert Transform is a transformation to convert ``for(...; ...;
+...)`` loops to use the new range-based loops in C++11. The transform is enabled
+with the :option:`-loop-convert` option of :program:`cpp11-migrate`.
+
+Three kinds of loops can be converted:
+
+-  Loops over statically allocated arrays
+-  Loops over containers, using iterators
+-  Loops over array-like containers, using ``operator[]`` and ``at()``
+
+Risk
+====
+
+TODO: Add code examples for which incorrect transformations are performed
+when the risk level is set to "Risky" or "Reasonable".
+
+Risky
+^^^^^
+
+In loops where the container expression is more complex than just a
+reference to a declared expression (a variable, function, enum, etc.),
+and some part of it appears elsewhere in the loop, we lower our confidence
+in the transformation due to the increased risk of changing semantics.
+Transformations for these loops are marked as `risky`, and thus will only
+be converted if the acceptable risk level is set to ``-risk=risky``.
+
+.. code-block:: c++
+
+  int arr[10][20];
+  int l = 5;
+
+  for (int j = 0; j < 20; ++j)
+    int k = arr[l][j] + l; // using l outside arr[l] is considered risky
+
+  for (int i = 0; i < obj.getVector().size(); ++i)
+    obj.foo(10); // using 'obj' is considered risky
+
+Reasonable (Default)
+^^^^^^^^^^^^^^^^^^^^
+
+If a loop calls ``.end()`` or ``.size()`` after each iteration, the
+transformation for that loop is marked as `reasonable`, and thus will
+be converted if the acceptable risk level is set to ``-risk=reasonable``
+(default) or higher.
+
+.. code-block:: c++
+
+  // using size() is considered reasonable
+  for (int i = 0; i < container.size(); ++i)
+    cout << container[i];
+
+Safe
+^^^^
+
+Any other loops that do not match the above criteria to be marked as
+`risky` or `reasonable` are marked `safe`, and thus will be converted
+if the acceptable risk level is set to ``-risk=safe`` or higher.
+
+.. code-block:: c++
+
+  int arr[] = {1,2,3};
+
+  for (int i = 0; i < 3; ++i)
+    cout << arr[i];
+
+Example
+=======
+
+Original:
+
+.. code-block:: c++
+
+  const int N = 5;
+  int arr[] = {1,2,3,4,5};
+  vector<int> v;
+  v.push_back(1);
+  v.push_back(2);
+  v.push_back(3);
+
+  // safe transform
+  for (int i = 0; i < N; ++i)
+    cout << arr[i];
+
+  // reasonable transform
+  for (vector<int>::iterator it = v.begin(); it != v.end(); ++it)
+    cout << *it;*
+
+  // reasonable transform
+  for (int i = 0; i < v.size(); ++i)
+    cout << v[i];
+
+After transformation with risk level set to ``-risk=reasonable`` (default):
+
+.. code-block:: c++
+
+  const int N = 5;
+  int arr[] = {1,2,3,4,5};
+  vector<int> v;
+  v.push_back(1);
+  v.push_back(2);
+  v.push_back(3);
+
+  // safe transform
+  for (auto & elem : arr)
+    cout << elem;
+
+  // reasonable transform
+  for (auto & elem : v)
+    cout << elem;
+
+  // reasonable transform
+  for (auto & elem : v)
+    cout << elem;
+

clang-tools-extra/docs/UseAutoTransform.rst

@@ -1,4 +1,4 @@
-.. index:: Loop Convert Transform
+.. index:: Use-Auto Transform
 
 ==================
 Use-Auto Transform

clang-tools-extra/docs/UseNullptrTransform.rst

@@ -0,0 +1,40 @@
+.. index:: Use-Nullptr Transform
+
+=====================
+Use-Nullptr Transform
+=====================
+
+The Use-Nullptr Transform is a transformation to convert the usage of null
+pointer constants (eg. ``NULL``, ``0``) to use the new C++11 ``nullptr``
+keyword. The transform is enabled with the :option:`-use-nullptr` option of
+:program:`cpp11-migrate`.
+
+Example
+=======
+
+.. code-block:: c++
+
+  void assignment() {
+    char *a = NULL;
+    char *b = 0;
+    char c = 0;
+  }
+
+  int *ret_ptr() {
+    return 0;
+  }
+
+
+transforms to:
+
+.. code-block:: c++
+
+  void assignment() {
+    char *a = nullptr;
+    char *b = nullptr;
+    char c = 0;
+  }
+
+  int *ret_ptr() {
+    return nullptr;
+  }

clang-tools-extra/docs/cpp11-migrate.rst

@@ -1,3 +1,5 @@
+.. index:: cpp11-migrate
+
 ===========================
 cpp11-migrate User's Manual
 ===========================
@@ -6,6 +8,8 @@ cpp11-migrate User's Manual
    :hidden:
 
    UseAutoTransform
+   UseNullptrTransform
+   LoopConvertTransform
 
 :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
@@ -32,8 +36,13 @@ Command Line Options
 
 .. option:: -loop-convert
 
-  Makes use of C++11 range-based for loops where possible.
+  Makes use of C++11 range-based for loops where possible. See
-  See :ref:`loop-convert-transformation`.
+  :doc:`LoopConvertTransform`.
+
+.. option:: -use-nullptr
+
+  Makes use of the new C++11 keyword ``nullptr`` where possible.
+  See :doc:`UseNullptrTransform`.
 
 .. option:: -use-auto
 
@@ -67,183 +76,21 @@ Command Line Options
     ``-risk=risky``
       Enable transformations that are likely to change semantics.
 
-  See :ref:`transformations` for further details for
+  The meaning of risk is handled differently for each transform. See
-  risk in individual transformations.
+  :ref:`transform documentation <transforms>` for details.
 
-.. option:: -use-nullptr
-
-  Makes use of the new C++11 keyword ``nullptr`` where possible.
-  See :ref:`nullptr-convert-transformation`.
 
 .. option:: -version
 
   Displays the version information of this tool.
 
-.. _transformations:
+.. _transforms:
 
 Transformations
 ===============
 
-.. _loop-convert-transformation:
+* :doc:`LoopConvertTransform`
 
-Loop Convert
+* :doc:`UseNullptrTransform`
-------------
 
-Loop convert is a transformation to convert ``for(...; ...; ...)`` loops to use
+* :doc:`UseAutoTransform`
-the new range-based loops in C++11.
-
-Three kinds of loops can be converted:
-
--  Loops over statically allocated arrays
--  Loops over containers, using iterators
--  Loops over array-like containers, using ``operator[]`` and ``at()``
-
-Risk
-^^^^
-
-TODO: Add code examples for which incorrect transformations are performed
-when the risk level is set to "Risky" or "Reasonable".
-
-Risky
-"""""
-
-In loops where the container expression is more complex than just a
-reference to a declared expression (a variable, function, enum, etc.),
-and some part of it appears elsewhere in the loop, we lower our confidence
-in the transformation due to the increased risk of changing semantics.
-Transformations for these loops are marked as `risky`, and thus will only
-be converted if the acceptable risk level is set to ``-risk=risky``.
-
-.. code-block:: c++
-
-  int arr[10][20];
-  int l = 5;
-
-  for (int j = 0; j < 20; ++j)
-    int k = arr[l][j] + l; // using l outside arr[l] is considered risky
-
-  for (int i = 0; i < obj.getVector().size(); ++i)
-    obj.foo(10); // using 'obj' is considered risky
-
-Reasonable (Default)
-""""""""""""""""""""
-
-If a loop calls ``.end()`` or ``.size()`` after each iteration, the
-transformation for that loop is marked as `reasonable`, and thus will
-be converted if the acceptable risk level is set to ``-risk=reasonable``
-(default) or higher.
-
-.. code-block:: c++
-
-  // using size() is considered reasonable
-  for (int i = 0; i < container.size(); ++i)
-    cout << container[i];
-
-Safe
-""""
-
-Any other loops that do not match the above criteria to be marked as
-`risky` or `reasonable` are marked `safe`, and thus will be converted
-if the acceptable risk level is set to ``-risk=safe`` or higher.
-
-.. code-block:: c++
-
-  int arr[] = {1,2,3};
-
-  for (int i = 0; i < 3; ++i)
-    cout << arr[i];
-
-Example
-^^^^^^^
-
-Original
-""""""""
-
-.. code-block:: c++
-
-  const int N = 5;
-  int arr[] = {1,2,3,4,5};
-  vector<int> v;
-  v.push_back(1);
-  v.push_back(2);
-  v.push_back(3);
-
-  // safe transform
-  for (int i = 0; i < N; ++i)
-    cout << arr[i];
-
-  // reasonable transform
-  for (vector<int>::iterator it = v.begin(); it != v.end(); ++it)
-    cout << *it;
-
-  // reasonable transform
-  for (int i = 0; i < v.size(); ++i)
-    cout << v[i];
-
-
-After transformation
-""""""""""""""""""""
-With risk level set to ``-risk=reasonable`` (default).
-
-.. code-block:: c++
-
-  const int N = 5;
-  int arr[] = {1,2,3,4,5};
-  vector<int> v;
-  v.push_back(1);
-  v.push_back(2);
-  v.push_back(3);
-
-  // safe transform
-  for (auto & elem : arr)
-    cout << elem;
-
-  // reasonable transform
-  for (auto & elem : v)
-    cout << elem;
-
-  // reasonable transform
-  for (auto & elem : v)
-    cout << elem;
-
-.. _nullptr-convert-transformation:
-
-Nullptr Convert
----------------
-
-Nullptr convert is a transformation to convert the usage of null pointer
-constants (eg. ``NULL``, ``0``) to use the new C++11 ``nullptr`` keyword.
-
-Example
-^^^^^^^
-
-Original
-""""""""
-
-.. code-block:: c++
-
-  void assignment() {
-    char *a = NULL;
-    char *b = 0;
-    char c = 0;
-  }
-
-  int *ret_ptr() {
-    return 0;
-  }
-
-
-After transformation
-""""""""""""""""""""
-
-.. code-block:: c++
-
-  void assignment() {
-    char *a = nullptr;
-    char *b = nullptr;
-    char c = 0;
-  }
-
-  int *ret_ptr() {
-    return nullptr;
-  }