Rename cpp11-migrate to clang-modernize.

There is no reason to expect this tool to be limited to C++11, it seems
very likely to be of on-going interest. It seems likely to be useful for
modernizing even as new libraries come out in TSes and other formats
than a complete standard. Fundamentally, we need something a bit more
general. After some discussion on the list, going with
'clang-modernize'.

I've tried to do a reasonably comprehensive job of fixing up the names,
but I may still have missed some. Feel free to poke me if you spot any
fallout here. Things I've tried reasonably hard to find and fix:

- cpp11-migrate -> clang-modernize
- Migrator -> Modernizer
- Clean up the introductory documentation that was C++11 specific.

I'll also point out that this tool continues to delight me. =] Also,
a huge thanks to those who have so carefully, thoroughly documented the
tool. The docs here are simply phenomenal. Every tool should be this
well documented. I hope I have updated the documentation reasonably
well, but I'm not very good at documentation, so review much
appreciated.

llvm-svn: 189960

1 files changed, 241 insertions, 0 deletions

diff --git a/clang-tools-extra/docs/ModernizerUsage.rst b/clang-tools-extra/docs/ModernizerUsage.rst
new file mode 100644
index 00000000000..c1c77460160
--- /dev/null
+++ b/clang-tools-extra/docs/ModernizerUsage.rst
@@ -0,0 +1,241 @@
+=====================
+clang-modernize Usage
+=====================
+
+``clang-modernize [options] <source0> [... <sourceN>] [-- [args]]``
+
+``<source#>`` specifies the path to the source to migrate. This path may be
+relative to the current directory.
+
+By default all transformations are applied. There are two ways to enable a
+subset of the transformations:
+
+1. Explicitly, by referring to the transform options directly, see
+   :ref:`transform-specific-command-line-options`.
+2. Implicitly, based on the compilers to support, see
+   :ref:`-for-compilers=\<string\> <for-compilers-option>`.
+
+If both ways of specifying transforms are used only explicitly specified
+transformations that are supported by the given compilers will be applied.
+
+General Command Line Options
+============================
+
+.. option:: -help
+
+  Displays tool usage instructions and command line options.
+
+.. option:: -version
+
+  Displays the version information of this tool.
+
+.. option:: -p=<build-path>
+
+  ``<build-path>`` is the directory containing a *compilation databasefile*, a
+  file named ``compile_commands.json``, which provides compiler arguments for
+  building each source file. CMake can generate this file by specifying
+  ``-DCMAKE_EXPORT_COMPILE_COMMANDS`` when running CMake. Ninja_, since v1.2 can
+  also generate this file with ``ninja -t compdb``. If the compilation database
+  cannot be used for any reason, an error is reported.
+
+  This option is ignored if ``--`` is present.
+
+.. option:: -- [args]
+
+  Another way to provide compiler arguments is to specify all arguments on the
+  command line following ``--``. Arguments provided this way are used for
+  *every* source file.
+
+  If neither ``--`` nor ``-p`` are specified a compilation database is
+  searched for starting with the path of the first-provided source file and
+  proceeding through parent directories. If no compilation database is found or
+  one is found and cannot be used for any reason then ``-std=c++11`` is used as
+  the only compiler argument.
+
+.. _Ninja: http://martine.github.io/ninja/
+
+.. 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.
+
+  The meaning of risk is handled differently for each transform. See
+  :ref:`transform documentation <transforms>` for details.
+
+.. option:: -final-syntax-check
+
+  After applying the final transform to a file, parse the file to ensure the
+  last transform did not introduce syntax errors. Syntax errors introduced by
+  earlier transforms are already caught when subsequent transforms parse the
+  file.
+
+.. option:: -format-style=<string>
+
+  After all transformations have been applied, reformat the changes using the
+  style ``string`` given as argument to the option. The style can be a builtin
+  style, one of LLVM, Google, Chromium, Mozilla; or a YAML configuration file.
+
+  If you want a place to start for using your own custom configuration file,
+  ClangFormat_ can generate a file with ``clang-format -dump-config``.
+
+  Example:
+
+  .. code-block:: c++
+    :emphasize-lines: 10-12,18
+
+      // file.cpp
+      for (std::vector<int>::const_iterator I = my_container.begin(),
+                                            E = my_container.end();
+           I != E; ++I) {
+        std::cout << *I << std::endl;
+      }
+
+      // No reformatting:
+      //     clang-modernize -use-auto file.cpp --
+      for (auto I = my_container.begin(),
+                                            E = my_container.end();
+           I != E; ++I) {
+        std::cout << *I << std::endl;
+      }
+
+      // With reformatting enabled:
+      //     clang-modernize -format-style=LLVM -use-auto file.cpp --
+      for (auto I = my_container.begin(), E = my_container.end(); I != E; ++I) {
+        std::cout << *I << std::endl;
+      }
+
+.. _ClangFormat: http://clang.llvm.org/docs/ClangFormat.html
+
+.. option:: -summary
+
+  Displays a summary of the number of changes each transform made or could have
+  made to each source file immediately after each transform is applied.
+  **Accepted** changes are those actually made. **Rejected** changes are those
+  that could have been made if the acceptable risk level were higher.
+  **Deferred** changes are those that might be possible but they might conflict
+  with other accepted changes. Re-applying the transform will resolve deferred
+  changes.
+
+.. _for-compilers-option:
+
+.. option:: -for-compilers=<string>
+
+  Select transforms targeting the intersection of language features supported by
+  the given compilers.
+
+  Four compilers are supported. The transforms are enabled according to this
+  table:
+
+  ===============  =====  ===  ====  ====
+  Transforms       clang  gcc  icc   mscv
+  ===============  =====  ===  ====  ====
+  AddOverride (1)  3.0    4.7  14    8
+  LoopConvert      3.0    4.6  13    11
+  PassByValue      3.0    4.6  13    11
+  ReplaceAutoPtr   3.0    4.6  13    11
+  UseAuto          2.9    4.4  12    10
+  UseNullptr       3.0    4.6  12.1  10
+  ===============  =====  ===  ====  ====
+
+  (1): if *-override-macros* is provided it's assumed that the macros are C++11
+  aware and the transform is enabled without regard to the supported compilers.
+
+  The structure of the argument to the `-for-compilers` option is
+  **<compiler>-<major ver>[.<minor ver>]** where **<compiler>** is one of the
+  compilers from the above table.
+
+  Some examples:
+
+  1. To support `Clang >= 3.0`, `gcc >= 4.6` and `MSVC >= 11`:
+
+     ``clang-modernize -for-compilers=clang-3.0,gcc-4.6,msvc-11 <args..>``
+
+     Enables LoopConvert, ReplaceAutoPtr, UseAuto, UseNullptr.
+
+  2. To support `icc >= 12` while using a C++11-aware macro for the `override`
+     virtual specifier:
+
+     ``clang-modernize -for-compilers=icc-12 -override-macros <args..>``
+
+     Enables AddOverride and UseAuto.
+
+  .. warning::
+
+    If your version of Clang depends on the GCC headers (e.g: when `libc++` is
+    not used), then you probably want to add the GCC version to the targeted
+    platforms as well.
+
+.. option:: -perf[=<directory>]
+
+  Turns on performance measurement and output functionality. The time it takes to
+  apply each transform is recorded by the migrator and written in JSON format
+  to a uniquely named file in the given ``<directory>``. All sources processed
+  by a single Modernizer process are written to the same output file. If
+  ``<directory>`` is not provided the default is ``./migrate_perf/``.
+
+  The time recorded for a transform includes parsing and creating source code
+  replacements.
+
+.. _transform-specific-command-line-options:
+
+Transform-Specific Command Line Options
+=======================================
+
+.. option:: -loop-convert
+
+  Makes use of C++11 range-based for loops where possible. See
+  :doc:`LoopConvertTransform`.
+
+.. option:: -use-nullptr
+
+  Makes use of the new C++11 keyword ``nullptr`` where possible.
+  See :doc:`UseNullptrTransform`.
+
+.. option:: -user-null-macros=<string>
+
+  ``<string>`` is a comma-separated list of user-defined macros that behave like
+  the ``NULL`` macro. The :option:`-use-nullptr` transform will replace these
+  macros along with ``NULL``. See :doc:`UseNullptrTransform`.
+
+.. option:: -use-auto
+
+  Replace the type specifier of variable declarations with the ``auto`` type
+  specifier. See :doc:`UseAutoTransform`.
+
+.. option:: -add-override
+
+  Adds the override specifier to member functions where it is appropriate. That
+  is, the override specifier is added to member functions that override a
+  virtual function in a base class and that don't already have the specifier.
+  See :doc:`AddOverrideTransform`.
+
+.. option:: -override-macros
+
+  Tells the Add Override Transform to locate a macro that expands to
+  ``override`` and use that macro instead of the ``override`` keyword directly.
+  If no such macro is found, ``override`` is still used. This option enables
+  projects that use such macros to maintain build compatibility with non-C++11
+  code.
+
+.. option:: -pass-by-value
+
+  Replace const-reference parameters by values in situations where it can be
+  beneficial.
+  See :doc:`PassByValueTransform`.
+
+.. option:: -replace-auto_ptr
+
+  Replace ``std::auto_ptr`` (deprecated in C++11) by ``std::unique_ptr`` and
+  wrap calls to the copy constructor and assignment operator with
+  ``std::move()``.
+  See :doc:`ReplaceAutoPtrTransform`.