Document -fobjc-weak as an extension.

Fixes rdar://24091053.

llvm-svn: 337525

clang/docs/LanguageExtensions.rst

@@ -1200,6 +1200,51 @@ Objective-C objects. ``__has_feature(objc_arc_fields)`` indicates that C structs
 are allowed to have fields that are pointers to Objective-C objects managed by
 automatic reference counting.
 
+.. _objc-weak:
+
+Weak references
+---------------
+
+Clang supports ARC-style weak and unsafe references in Objective-C even
+outside of ARC mode.  Weak references must be explicitly enabled with
+the ``-fobjc-weak`` option; use ``__has_feature((objc_arc_weak))``
+to test whether they are enabled.  Unsafe references are enabled
+unconditionally.  ARC-style weak and unsafe references cannot be used
+when Objective-C garbage collection is enabled.
+
+Except as noted below, the language rules for the ``__weak`` and
+``__unsafe_unretained`` qualifiers (and the ``weak`` and
+``unsafe_unretained`` property attributes) are just as laid out
+in the :doc:`ARC specification <AutomaticReferenceCounting>`.
+In particular, note that some classes do not support forming weak
+references to their instances, and note that special care must be
+taken when storing weak references in memory where initialization
+and deinitialization are outside the responsibility of the compiler
+(such as in ``malloc``-ed memory).
+
+Loading from a ``__weak`` variable always implicitly retains the
+loaded value.  In non-ARC modes, this retain is normally balanced
+by an implicit autorelease.  This autorelease can be suppressed
+by performing the load in the receiver position of a ``-retain``
+message send (e.g. ``[weakReference retain]``); note that this performs
+only a single retain (the retain done when primitively loading from
+the weak reference).
+
+For the most part, ``__unsafe_unretained`` in non-ARC modes is just the
+default behavior of variables and therefore is not needed.  However,
+it does have an effect on the semantics of block captures: normally,
+copying a block which captures an Objective-C object or block pointer
+causes the captured pointer to be retained or copied, respectively,
+but that behavior is suppressed when the captured variable is qualified
+with ``__unsafe_unretained``.
+
+Note that the ``__weak`` qualifier formerly meant the GC qualifier in
+all non-ARC modes and was silently ignored outside of GC modes.  It now
+means the ARC-style qualifier in all non-GC modes and is no longer
+allowed if not enabled by either ``-fobjc-arc`` or ``-fobjc-weak``.
+It is expected that ``-fobjc-weak`` will eventually be enabled by default
+in all non-GC Objective-C modes.
+
 .. _objc-fixed-enum:
 
 Enumerations with a fixed underlying type