Add documentation for @available

[thakis]

Summary

Based on https://devstreaming-cdn.apple.com/videos/wwdc/2017/411a7o9phe4uekm/411/411_whats_new_in_llvm.pdf

(I couldn't find a way to play the corresponding video on linux, so I didn't look at that.)

[erik.pilkington]

This looks great, thanks for working on this! LGTM, but @arphaman might have some thoughts.

docs/LanguageExtensions.rst

1290

did you mean to remove this?

1309

Don't forget the '*', ie @available(macos 10.12, *)!

[thakis]

comments

docs/LanguageExtensions.rst

1290

I meant to move it above the "protocol-qualifier mangling of parameters" section; I think that's where it belongs. Did that.

1309

Done, thanks. What does the * do, by the way? :-)

[erik.pilkington]

docs/LanguageExtensions.rst

1309

Its supposed to make explicit that if the platform isn't listed in the @available, the true branch is taken and diagnostics are emitted in the then stmt using the deployment target version. The idea is that if a new platform is introduced, it would use existing APIs and it would be unfortunate if it broke everything.

Now that I think about it, this should probably be mentioned, as its probably the most counter-intuitive part of this feature. Maybe something like: "If the platform your running on isn't listed in the @available, then the the true branch of the if is taken and warnings are emitted against the current deployment target."? It might also be nice if you added another OS to this example, like @available(macOS 10.12, iOS 10, *)?

[thakis]

Document *, add example with multiple platforms

[arphaman]

Thanks for doing this! I have some comments:

docs/LanguageExtensions.rst

1277

possible to use

1278

Nit: older versions of macOS or iOS

1281

...in the OS that's newer than the target OS (as determined by the minimum deployment version), ..

1286

NIT: run fine on newer systems, but crash on older systems.

1291

I would reword this sentence like this:
When a method that's introduced in the OS newer than the target OS is called, a -Wunguarded-availability warning is emitted if that call is not guarded:

1303

Nit: and to avoid the crash on macOS 10.11

1342

Nit: in C and C++ code

1347

We don't want to encourage usage of undocumented/private APIs before they are officially made public for a number of reasons. Can you please remove or rewrite this paragraph (ideally removing/replacing the specific example)?

[thakis]

Thanks, all done, much better!

docs/LanguageExtensions.rst

1347

I removed it from this patch, but this is something that's necessary every now and then. If there's no guidance on this, chances are people will come up with worse hacks :-) So I think having some documentation on this is a good thing. Once this is in, I'll send out a follow-up and we can iterate on this paragraph there (or decide to omit it and let each project decide on what to do here.)

[thakis]

arphaman comments

[sdy]

docs/LanguageExtensions.rst

1274

I think "Objective-C" is redundant, this is already in the ObjC section and most of the other headers don't start with "Objective-C".

1274

@available should probably be wrapped in backticks.

1278

I thought this flag was --mmacosx-version-min?
Nit: I would remove the comma after "versions".

1317

I would say "The * is required and means…"

1331

attributes ➔ attribute

1333

Maybe something like "…which will suppress the warning and require that calls to my_fun() are checked."

[thakis]

sdy comments

[thakis]

Mostly done, thanks!

docs/LanguageExtensions.rst

1274

The one below and the two above start with "Objective-C".

1278

Nicos-MacBook-Pro:llvm-build thakis$ bin/clang -mmacosx-version-min=10.11 -c test.mm
Nicos-MacBook-Pro:llvm-build thakis$ bin/clang --mmacosx-version-min=10.11 -c test.mm
clang-3.5: error: unsupported option '--mmacosx-version-min=10.11'

Removed comma.

[thakis]

I went ahead and landed this in r308044, given that I addressed the nits and removed the possibly contentious bits. Happy to address remaining nits in a follow-up.

[sdy]

docs/LanguageExtensions.rst

1278

Sorry, I added an extra dash in the comment. I meant that the CL says mmacosx-version-info, not min.

[thakis]

docs/LanguageExtensions.rst

1278

Oooh I see. Thanks, fixed in http://llvm.org/viewvc/llvm-project?rev=308048&view=rev

[arphaman]

docs/LanguageExtensions.rst

1347

Ok, sure.

[thakis]

landed long ago in 11cafc82b72a80fb9a7266bbda7fc7a0cc1b51a0 / 564004ae78c61a9292a15f8ed0500016b93ea74e

docs/LanguageExtensions.rst

 Query for these features with ``__has_attribute(ns_consumed)``,
 ``__has_attribute(ns_returns_retained)``, etc.
 
+Objective-C @available
+----------------------
 
+It is possible to use the newest SDK but still build a program that can run on
+older versions of macOS and iOS by passing ``-mmacosx-version-info=`` /
+``--miphoneos-version-min=``.
+
+Before LLVM 5.0, when calling a function that exists only in the OS that's
+newer than the target OS (as determined by the minimum deployment version),
+programmers had to carefully check if the function exists at runtime, using
+null checks for weakly-linked C functions, ``+class`` for Objective-C classes,
+and ``-respondsToSelector:`` or ``+instancesRespondToSelector:`` for
+Objective-C methods.  If such a check was missed, the program would compile
+fine, run fine on newer systems, but crash on older systems.
+
+As of LLVM 5.0, ``-Wunguarded-availability`` uses the `availability attributes
+<http://clang.llvm.org/docs/AttributeReference.html#availability>`_ together
+with the new ``@available()`` keyword to assist with this issue.
+When a method that's introduced in the OS newer than the target OS is called, a
+-Wunguarded-availability warning is emitted if that call is not guarded:
+
+.. code-block:: objc
+
+  void my_fun(NSSomeClass* var) {
+    // If fancyNewMethod was added in e.g. macOS 10.12, but the code is
+    // built with -mmacosx-version-min=10.11, then this unconditional call
+    // will emit a -Wunguarded-availability warning:
+    [var fancyNewMethod];
+  }
+
+To fix the warning and to avoid the crash on macOS 10.11, wrap it in
+``if(@available())``:
+
+.. code-block:: objc
+
+  void my_fun(NSSomeClass* var) {
+    if (@available(macOS 10.12, *)) {
+      [var fancyNewMethod];
+    } else {
+      // Put fallback behavior for old macOS versions (and for non-mac
+      // platforms) here.
+    }
+  }
+
+The ``*`` is required and means that platforms not explicitly listed will take
+the true branch, and the compiler will emit ``-Wunguarded-availability``
+warnings for unlisted platforms based on those platform's deployment target.
+More than one platform can be listed in ``@available()``:
+
+.. code-block:: objc
+
+  void my_fun(NSSomeClass* var) {
+    if (@available(macOS 10.12, iOS 10, *)) {
+      [var fancyNewMethod];
+    }
+  }
+
+If the caller of ``my_fun()`` already checks that ``my_fun()`` is only called
+on 10.12, then add an `availability attribute
+<http://clang.llvm.org/docs/AttributeReference.html#availability>`_ to it,
+which will also suppress the warning and require that calls to my_fun() are
+checked:
+
+.. code-block:: objc
+
+  API_AVAILABLE(macos(10.12)) void my_fun(NSSomeClass* var) {
+    [var fancyNewMethod];  // Now ok.
+  }
+
+``@available()`` is only available in Objective-C code.  To use the feature
+in C and C++ code, use the ``__builtin_available()`` spelling instead.
+
+If existing code uses null checks or ``-respondsToSelector:``, it should
+be changed to use ``@available()`` (or ``__builtin_available``) instead.
+
+``-Wunguarded-availability`` is disabled by default, but
+``-Wunguarded-availability-new``, which only emits this warning for APIs
+that have been introduced in macOS >= 10.13, iOS >= 11, watchOS >= 4 and
+tvOS >= 11, is enabled by default.
+
+.. _langext-overloading:
+
 Objective-C++ ABI: protocol-qualifier mangling of parameters
 ------------------------------------------------------------
 

 Query the presence of this new mangling with
 ``__has_feature(objc_protocol_qualifier_mangling)``.
 
-.. _langext-overloading:
-
 Initializer lists for complex numbers in C
 ==========================================
 

include/clang/Basic/AttrDocs.td

 
   void f(void) __attribute__((availability(macos,introduced=10.4,deprecated=10.6,obsoleted=10.7)));
 
-The availability attribute states that ``f`` was introduced in Mac OS X 10.4,
-deprecated in Mac OS X 10.6, and obsoleted in Mac OS X 10.7.  This information
+The availability attribute states that ``f`` was introduced in macOS 10.4,
+deprecated in macOS 10.6, and obsoleted in macOS 10.7.  This information
 is used by Clang to determine when it is safe to use ``f``: for example, if
-Clang is instructed to compile code for Mac OS X 10.5, a call to ``f()``
-succeeds.  If Clang is instructed to compile code for Mac OS X 10.6, the call
+Clang is instructed to compile code for macOS 10.5, a call to ``f()``
+succeeds.  If Clang is instructed to compile code for macOS 10.6, the call
 succeeds but Clang emits a warning specifying that the function is deprecated.
-Finally, if Clang is instructed to compile code for Mac OS X 10.7, the call
+Finally, if Clang is instructed to compile code for macOS 10.7, the call
 fails because ``f()`` is no longer available.
 
 The availability attribute is a comma-separated list starting with the

   command-line arguments.
 
 ``macos``
-  Apple's Mac OS X operating system.  The minimum deployment target is
+  Apple's macOS operating system.  The minimum deployment target is
   specified by the ``-mmacosx-version-min=*version*`` command-line argument.
   ``macosx`` is supported for backward-compatibility reasons, but it is
   deprecated.

   - (id)method __attribute__((availability(macos,introduced=10.5))); // error: this method was available via the base class in 10.4
   @end
   }];
+
+Starting with the macOS 10.12 SDK, the ``API_AVAILABLE`` macro from
+``<os/availability.h>`` can simplify the spelling:
+
+.. code-block:: objc
+
+  @interface A
+  - (id)method API_AVAILABLE(macos(10.11)));
+  - (id)otherMethod API_AVAILABLE(macos(10.11), ios(11.0));
+  @end
+
+Also see the documentation for `@available
+<http://clang.llvm.org/docs/LanguageExtensions.html#objective-c-@available>`_
 }
 
 def ExternalSourceSymbolDocs : Documentation {