Add user documentation for cpp11-migrate

Adding an RST document for cpp11-migrate. This user documentation explains
command line options, transformations, risk level and how it applies to
loop convert, and code examples of transformations.

There is a TODO task under "Risk" for "Loop Convert" to find code examples
that produce incorrect transformations that change semantics. The definition
of risk in loop convert and instances where the confidence level is lowered
will need to be looked at more carefully.

Information for all new features (including verbose output, auto transform)
will be added in a later change.

Author: Jack Yang <jack.wang@intel.com>
Reviewer: grigozavr
llvm-svn: 176046

diff --git a/clang-tools-extra/docs/cpp11-migrate.rst b/clang-tools-extra/docs/cpp11-migrate.rst
new file mode 100644 (file)
index 0000000..55a5d4b
--- /dev/null
+++ b/clang-tools-extra/docs/cpp11-migrate.rst
@@ -0,0 +1,239 @@
+===========================
+cpp11-migrate User's Manual
+===========================
+
+: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.
+
+Basic Usage
+===========
+
+``cpp11-migrate [options] <source0> [... <sourceN>]``
+
+``<source0>...`` specify the paths of files in the CMake source tree,
+with the same requirements as other tools built on LibTooling.
+
+Command Line Options
+--------------------
+
+.. option:: -fatal-assembler-warnings
+
+  Treat all compiler warnings as errors.
+
+.. option:: -help
+
+  Displays tool usage instructions and command line options.
+
+.. option:: -loop-convert
+
+  Makes use of C++11 range-based for loops where possible.
+  See :ref:`loop-convert-transformation`.
+
+.. option:: -p=<build-path>
+
+  ``<build-path>`` is a CMake build directory containing a file named
+  ``compile_commands.json`` which provides compiler options for building
+  each source file and can be generated by specifying
+  ``-DCMAKE_EXPORT_COMPILE_COMMANDS`` when running CMake. If ``<build-path>``
+  is not provided the ``compile_commands.json`` file is searched for through
+  all parent directories.
+
+  Alternatively, one can provide compile options to be applied to every
+  source file after the optional ``--``.
+
+.. option:: -risk=<risk-level>
+
+  Some transformations may cause a change in semantics. In such cases the
+  maximum acceptable risk level specified through the ``-risk`` command
+  line option decides whether or not a transformation is applied.
+
+  Three different risk level options are available:
+
+    ``-risk=safe``
+      Perform only safe transformations.
+    ``-risk=reasonable`` (default)
+      Enable transformations that may change semantics.
+    ``-risk=risky``
+      Enable transformations that are likely to change semantics.
+
+  See :ref:`transformations` for further details for
+  risk in individual transformations.
+
+.. 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:
+
+Transformations
+===============
+
+.. _loop-convert-transformation:
+
+Loop Convert
+------------
+
+Loop convert is a transformation to convert ``for(...; ...; ...)`` loops to use
+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;
+  }

diff --git a/clang-tools-extra/docs/index.rst b/clang-tools-extra/docs/index.rst
index b45bb88..d39f54c 100644 (file)
--- a/clang-tools-extra/docs/index.rst
+++ b/clang-tools-extra/docs/index.rst
@@ -8,7 +8,9 @@
 Contents:
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
+
+   cpp11-migrate