[PATCH] Add limitations to loop convert user doc

[Edwin Vane]

================
Comment at: docs/LoopConvertTransform.rst:126
@@ +125,3 @@
+There are certain situations where the tool may erroneously perform
+transformations that removes information and changes semantics. The following
+is a list of known limitations of the transform. Users of the tool should be
----------------
removes->remove
changes->change
(it's the 'transformations' making these changes not the 'tool' hence the plurality change).

================
Comment at: docs/LoopConvertTransform.rst:128
@@ +127,3 @@
+is a list of known limitations of the transform. Users of the tool should be
+aware of the behaviour and limitations of the transform.
+
----------------
These last two sentences repeate "limitations of the transform". See if you can coalesce these two into something more succinct.

================
Comment at: docs/LoopConvertTransform.rst:146
@@ +145,3 @@
+each iteration, the semantics of the transformed loop may differ.
+
+.. code-block:: c++
----------------
No commas necessary in this sentence.

================
Comment at: docs/LoopConvertTransform.rst:160
@@ +159,3 @@
+
+As explained previously, calling member functions of the container in the body
+of the loop is considered `risky`. If the called member function modifies the
----------------
Perhaps previously->above?

================
Comment at: docs/LoopConvertTransform.rst:163
@@ +162,3 @@
+container, the semantics of the converted loop will differ due to ``.end()``
+only being called at the start of the loop.
+
----------------
-> "being called only once"

================
Comment at: docs/LoopConvertTransform.rst:156
@@ +155,3 @@
+  // therefore the semantics of the header will not change.
+  for (iterator it = container.begin(), e = container.end(); it != e; ++it) { }
+
----------------
I think I'd put this example first to illustrate what a ranged-base for is like. Then show the other example to highlight the difference once the reader has the baseline in mind.

================
Comment at: docs/LoopConvertTransform.rst:195
@@ +194,3 @@
+
+Semantics may also be affected if ``.end()`` has side effects. For example, in
+the case where calls to ``.end()`` are logged, the semantics may change in the
----------------
may->will. If there are side effects, semantics will definitely change.

================
Comment at: docs/LoopConvertTransform.rst:196
@@ +195,3 @@
+Semantics may also be affected if ``.end()`` has side effects. For example, in
+the case where calls to ``.end()`` are logged, the semantics may change in the
+transformed loop if ``.end()`` was called after each iteration.
----------------
may->will again.

================
Comment at: docs/LoopConvertTransform.rst:197
@@ +196,3 @@
+the case where calls to ``.end()`` are logged, the semantics may change in the
+transformed loop if ``.end()`` was called after each iteration.
+
----------------
was (originally?) called

================
Comment at: docs/LoopConvertTransform.rst:210
@@ +209,3 @@
+Similarly, if ``operator->()`` was overloaded to have side effects, such as
+logging, the semantics will change. In the original loop, we may have used the
+arrow operator to dereference the iterator to call a member. This is no longer
----------------
No comma after loop.

================
Comment at: docs/LoopConvertTransform.rst:212
@@ +211,3 @@
+arrow operator to dereference the iterator to call a member. This is no longer
+necessary in the transformed loop, since we will replace it to use the dot
+operator. Therefore any side effect of the arrow operator will no longer be
----------------
no comma after loop. Also, more 'royal we' here. Just say "since the transform will..."

================
Comment at: docs/LoopConvertTransform.rst:231
@@ +230,3 @@
+While most of the transform's risk analysis is dedicated to determining whether
+the iterator or container was modified, it is possible to circumvent the
+analysis by accessing and modifying the container through a pointer or
----------------
modified within the loop,

================
Comment at: docs/LoopConvertTransform.rst:235
@@ +234,3 @@
+
+If the container were directly used instead of using the pointer or reference,
+the following transformation would have only been applied at the ``-risk=risky``
----------------
no comma after reference.

================
Comment at: docs/LoopConvertTransform.rst:237
@@ +236,3 @@
+the following transformation would have only been applied at the ``-risk=risky``
+level, since calling a member function of the container is considered `risky`.
+Loop convert cannot identify expressions associated with the container that are
----------------
no comma after level.

================
Comment at: docs/LoopConvertTransform.rst:238
@@ +237,3 @@
+level, since calling a member function of the container is considered `risky`.
+Loop convert cannot identify expressions associated with the container that are
+different than the one used in the loop header, therefore the transformation
----------------
Use "The transform" or "The Loop Convert transform"


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