[PATCH] Add user documentation for cpp11-migrate

[Dmitri Gribenko]

  This document is not consistent with section adornments.  LLVM and Clang use:

  ```
  ====
  Title
  ====

  Level 1
  =======

  Level 2
  -------

  level 3
  ^^^^^^^

  level 4
  """""""
  ```

  You might find llvm/docs/SphinxQuickstartTemplate.rst useful.


================
Comment at: cpp11-migrate/docs/cpp11-migrate.rst:5
@@ +4,3 @@
+
+cpp11-migrate is a standalone tool used to automatically convert legacy
+C++ code to use features of the new C++11 standard where appropriate.
----------------
```
  :program:`cpp11-migrate`
```

================
Comment at: cpp11-migrate/docs/cpp11-migrate.rst:30
@@ +29,3 @@
+  Makes use of C++11 range-based for loops where possible.
+  See :ref:`Loop Convert <loop-convert-transformation>`.
+
----------------
```
  :ref:`loop-convert-transformation`
```

will copy the section title automatically.

================
Comment at: cpp11-migrate/docs/cpp11-migrate.rst:65
@@ +64,3 @@
+  Makes use of the new C++11 keyword ``nullptr`` where possible.
+  See :ref:`Nullptr Convert<nullptr-convert-transformation>`.
+
----------------
```
  :ref:`nullptr-convert-transformation`
```

================
Comment at: cpp11-migrate/docs/cpp11-migrate.rst:59
@@ +58,3 @@
+
+  See :ref:`Transformations<transformations>` for further details for
+  risk in individual transformations.
----------------
```
  :ref:`transformations`
```

================
Comment at: cpp11-migrate/docs/cpp11-migrate.rst:81
@@ +80,3 @@
+
+Loop convert is a transformation to convert legacy C++ ``for``
+loops to use the new range-based loops in C++11.
----------------
I'd not call these "legacy"...

================
Comment at: cpp11-migrate/docs/cpp11-migrate.rst:88
@@ +87,3 @@
+-  Loops over containers, using iterators
+-  Loops over array-like containers, using operator[] and at()
+
----------------
```
  ``operator[]`` and ``at()``
```

================
Comment at: cpp11-migrate/docs/cpp11-migrate.rst:129-131
@@ +128,5 @@
+
+  // using .size() is considered reasonable
+  for (int i = 0; i < v.size(); ++i)
+    cout << v[i];
+
----------------
It might be a good idea to show examples where "risky" or "default" change the semantics.


================
Comment at: cpp11-migrate/docs/cpp11-migrate.rst:231
@@ +230,3 @@
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Ran with risk level set to ``-risk=reasonable`` (default).
+
----------------
Is the nullptr transform always safe?  Can it change semantics?  (If yes, an example would help.)



http://llvm-reviews.chandlerc.com/D339