Clarify when fix-it hints on warnings are appropriate

[aaronpuchert]

Summary

This is not a change in the rules, it's meant as a clarification about
warnings. Since the recovery from warnings is a no-op, the fix-it hints
on warnings shouldn't change anything. Anything that doesn't just
suppress the warning and changes the meaning of the code (even if it's
for the better) should be on an additional note.

[aaronpuchert]

Feel free to suggest better wording, I'm not a native speaker.

[aaron.ballman]

Thank you for working on this!

docs/InternalsManual.rst

426–428 ↗

(On Diff #201469)

How about:

Fix-it hints on  a warning must not change the meaning of code, only clarify it. For example, adding parentheses in case of counterintuitive precedence to clarify the order of operations.

[aaronpuchert]

docs/InternalsManual.rst

426–428 ↗

(On Diff #201469)

must not change the meaning of code, only clarify it

Wasn't sure about the order between “not change”/“only clarify”. If it sounds better to you, I'll take that.

For example, adding parentheses in case of counterintuitive precedence to clarify the order of operations.

Can we add a finite verb, like “For example, it would be fine to add parantheses ...”

Also, I would probably shorten “in case of counterintuitive precedence to clarify the order of operations” to “to clarify the precedence of operators.” So we have

For example, it would be fine to add parantheses to clarify the precedence of operators.

[aaron.ballman]

docs/InternalsManual.rst

426–428 ↗

(On Diff #201469)

Wasn't sure about the order between “not change”/“only clarify”. If it sounds better to you, I'll take that.

I think the most important bit is that it must not change code meaning, so that's why I suggest putting it first.

For example, it would be fine to add parantheses to clarify the precedence of operators.

I like it! Though I'd spell it parentheses instead. ;-)

[aaronpuchert]

docs/InternalsManual.rst

426–428 ↗

(On Diff #201469)

Though I'd spell it parentheses instead. ;-)

There must have been a red squiggly line, but I've apparently decided to ignore it.

[aaronpuchert]

Put the important part first, and the rest in a separate sentence.

[rsmith]

Thanks, looks good to me.

[aaron.ballman]

LGTM!

cfe/trunk/docs/InternalsManual.rst

 problem.
 
 Fix-it hints on errors and warnings need to obey these rules:
 
 * Since they are automatically applied if ``-Xclang -fixit`` is passed to the
   driver, they should only be used when it's very likely they match the user's
   intent.
 * Clang must recover from errors as if the fix-it had been applied.
+* Fix-it hints on a warning must not change the meaning of the code.
+  However, a hint may clarify the meaning as intentional, for example by adding
+  parentheses when the precedence of operators isn't obvious.
 
 If a fix-it can't obey these rules, put the fix-it on a note.  Fix-its on notes
 are not applied automatically.
 
 All fix-it hints are described by the ``FixItHint`` class, instances of which
 should be attached to the diagnostic using the ``<<`` operator in the same way
 that highlighted source ranges and arguments are passed to the diagnostic.
 Fix-it hints can be created with one of three constructors: