cpp11-migrate: Docs refresh

* Documented new command-line options.
* Moved usage to a new page.
  * Usage now split into general options and transform-related options.
* Main Migrator page now contains getting started and getting involved
  information.
  * Also included a JIRA issue collector button for logging bugs.

llvm-svn: 183417

3 files changed, 228 insertions, 92 deletions

diff --git a/clang-tools-extra/docs/AddOverrideTransform.rst b/clang-tools-extra/docs/AddOverrideTransform.rst
index ea537fefc0f..03f9494e23f 100644
--- a/clang-tools-extra/docs/AddOverrideTransform.rst
+++ b/clang-tools-extra/docs/AddOverrideTransform.rst
@@ -25,6 +25,16 @@ For example:
     void h() const override;
   };
 
+Using Expands-to-Override Macros
+--------------------------------
+
+Like LLVM's ``LLVM_OVERRIDE``, several projects have macros that conditionally
+expand to the ``override`` keyword when compiling with C++11 features enabled.
+To maintain compatibility with non-C++11 builds, the Add-Override Transform
+supports detection and use of these macros instead of using the ``override``
+keyword directly. Specify ``-override-macros`` on the command line to the
+Migrator to enable this behavior.
+
 
 Known Limitations
 -----------------
diff --git a/clang-tools-extra/docs/MigratorUsage.rst b/clang-tools-extra/docs/MigratorUsage.rst
new file mode 100644
index 00000000000..5c762bd661a
--- /dev/null
+++ b/clang-tools-extra/docs/MigratorUsage.rst
@@ -0,0 +1,128 @@
+===================
+cpp11-migrate Usage
+===================
+
+``cpp11-migrate [options] <source0> [... <sourceN>] [-- [args]]``
+
+``<source#>`` specifies the path to the source to migrate. This path may be
+relative to the current directory.
+
+At least one transform must be enabled.
+
+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 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 ``<build-path>`` is
+  not provided the ``compile_commands.json`` file is searched for through all
+  parent directories.
+
+.. 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 ``-p`` is not specified, ``--`` is necessary, even if no compiler
+  arguments are required.
+
+.. _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:: -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.
+
+.. 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 Migrator 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
+---------------------------------------
+
+.. 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.
+
diff --git a/clang-tools-extra/docs/cpp11-migrate.rst b/clang-tools-extra/docs/cpp11-migrate.rst
index 70e833683dc..bba4df11fe6 100644
--- a/clang-tools-extra/docs/cpp11-migrate.rst
+++ b/clang-tools-extra/docs/cpp11-migrate.rst
@@ -1,8 +1,8 @@
 .. index:: cpp11-migrate
 
-===========================
-cpp11-migrate User's Manual
-===========================
+============================
+C++11 Migrator User's Manual
+============================
 
 .. toctree::
    :hidden:
@@ -11,107 +11,105 @@ cpp11-migrate User's Manual
    UseNullptrTransform
    LoopConvertTransform
    AddOverrideTransform
+   MigratorUsage
 
 :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:: -help
-
-  Displays tool usage instructions and 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:: -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.
-
-  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:: -fatal-assembler-warnings
-
-  Treat all compiler warnings as errors.
-
-
-.. option:: -version
-
-  Displays the version information of this tool.
+Getting Started
+---------------
+
+To build from source:
+
+1. Read `Getting Started with the LLVM System`_ and `Clang Tools
+   Documentation`_ for information on getting sources for LLVM, Clang, and
+   Clang Extra Tools.
+
+2. `Getting Started with the LLVM System`_ and `Building LLVM with CMake`_ give
+   directions for how to build. With sources all checked out into the
+   right place the LLVM build will build Clang Extra Tools and their
+   dependencies automatically.
+
+   * If using CMake, you can also use the ``cpp11-migrate`` target to build
+     just the Migrator and its dependencies.
+
+Before continuing, take a look at :doc:`MigratorUsage` to see how to invoke the
+Migrator.
+
+Before running the Migrator on code you'll need the arguments you'd normally
+pass to the compiler. If you're migrating a single file with few compiler
+arguments, it might be easier to pass the compiler args on the command line
+after ``--``. If you're working with multiple files or even a single file
+with many compiler args, it's probably best to use a *compilation database*.
+
+A `compilation database`_ contains the command-line arguments for multiple
+files. If the code you want to transform can be built with CMake, you can
+generate this database easily by running CMake with the
+``-DCMAKE_EXPORT_COMPILE_COMMANDS`` option. The Ninja_ build system, since
+v1.2, can create this file too using the *compdb* tool: ``ninja -t compdb``. If
+you're not already using either of these tools or cannot easily make use of
+them you might consider looking into Bear_.
+
+In addition to the compiler arguments you usually build your code with, you must
+provide the option for enabling C++11 features. For clang and versions of gcc
+≥ v4.8 this is ``-std=c++11``.
+
+Now with compiler arguments, the Migrator can be applied to source. Sources are
+transformed in place and changes are only written to disk if compilation errors
+aren't caused by the transforms. Each transform will re-parse the output from
+the previous transform. The output from the last transform is not checked
+unless ``-final-syntax-check`` is enabled.
+
+
+.. _Ninja: http://martine.github.io/ninja/
+.. _Bear: https://github.com/rizsotto/Bear
+.. _compilation database: http://clang.llvm.org/docs/JSONCompilationDatabase.html
+.. _Getting Started with the LLVM System: http://llvm.org/docs/GettingStarted.html
+.. _Building LLVM with CMake: http://llvm.org/docs/CMake.html
+.. _Clang Tools Documentation: http://clang.llvm.org/docs/ClangTools.html
+
+Getting Involved
+----------------
+
+If you find a bug
+
+.. raw:: html
+
+  <input type="button" id="logbug" value="Log a Bug!" />
+  <script type="text/javascript" src="https://cpp11-migrate.atlassian.net/s/en_USpfg3b3-1988229788/6095/34/1.4.0-m2/_/download/batch/com.atlassian.jira.collector.plugin.jira-issue-collector-plugin:issuecollector/com.atlassian.jira.collector.plugin.jira-issue-collector-plugin:issuecollector.js?collectorId=50813874"></script>
+  <script type="text/javascript">window.ATL_JQ_PAGE_PROPS =  {
+    "triggerFunction": function(showCollectorDialog) {
+      //Requries that jQuery is available! 
+      jQuery("#logbug").click(function(e) {
+        e.preventDefault();
+        showCollectorDialog();
+      });
+    }};
+  </script>
+
+Bugs and feature development of the Migrator are tracked at
+http://cpp11-migrate.atlassian.net. If you want to get involved the front page
+shows a list of outstanding issues or you can browse around the project to get
+familiar. To take on issues or contribute feature requests and/or bug reports
+you need to sign up for an account from the `log in page`_. An account also
+lets you sign up for notifications on issues or vote for unassigned issues to
+be completed.
+
+.. _log in page: https://cpp11-migrate.atlassian.net/login
 
 .. _transforms:
 
 Transformations
-===============
+---------------
+
+The Migrator is a collection of independent transforms which can be
+independently enabled. The transforms currently implemented are:
 
 * :doc:`LoopConvertTransform`
 
 * :doc:`UseNullptrTransform`
 
 * :doc:`UseAutoTransform`
+
+* :doc:`AddOverrideTransform`