Add an explanation of -Wobjc-literal-compare to the "Objective-C Literals" page

(per Jean-Daniel's suggestion to keep around an explanation of why
direct comparisons on ObjC literals are a bad idea)

git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@159972 91177308-0d34-0410-b5e6-96231b3b80d8

diff --git a/docs/ObjectiveCLiterals.html b/docs/ObjectiveCLiterals.html
index 33f73e4a5b916ac06f0eefea68adab74f0bb0a1c..11751a6acda8f33c4fbe00658b01a8939db0d627 100644 (file)
--- a/docs/ObjectiveCLiterals.html
+++ b/docs/ObjectiveCLiterals.html
@@ -328,6 +328,12 @@ object[key] = newValue;
 
 <p>Programs can use object subscripting with Objective-C object pointers of type <code>id</code>. Normal dynamic message send rules apply; the compiler must see <i>some</i> declaration of the subscripting methods, and will pick the declaration seen first.</p>
 
+<h2>Caveats</h2>
+
+<p>Objects created using the literal or boxed expression syntax are not guaranteed to be uniqued by the runtime, but nor are they guaranteed to be newly-allocated. As such, the result of performing direct comparisons against the location of an object literal (using <code>==</code>, <code>!=</code>, <code>&lt;</code>, <code>&lt;=</code>, <code>&gt;</code>, or <code>&gt;=</code>) is not well-defined. This is usually a simple mistake in code that intended to call the <code>isEqual:</code> method (or the <code>compare:</code> method).</p>
+
+<p>This caveat applies to compile-time string literals as well. Historically, string literals (using the <code>@"..."</code> syntax) have been uniqued across translation units during linking. This is an implementation detail of the compiler and should not be relied upon. If you are using such code, please use global string constants instead (<code>NSString * const MyConst = @"..."</code>) or use <code>isEqual:</code>.</p>
+
 <h2>Grammar Additions</h2>
 
 <p>To support the new syntax described above, the Objective-C <code>@</code>-expression grammar has the following new productions:</p>