[PATCH] D35379: Add documentation for @available

[Alex Lorenz via Phabricator via cfe-commits]

arphaman added a comment.

Thanks for doing this! I have some comments:



================
Comment at: docs/LanguageExtensions.rst:1277
 
+It is possible use the newest SDK but still build a program that can run on
+older macOS and iOS versions, by passing ``-mmacosx-version-info=`` /
----------------
possible to use


================
Comment at: docs/LanguageExtensions.rst:1278
+It is possible use the newest SDK but still build a program that can run on
+older macOS and iOS versions, by passing ``-mmacosx-version-info=`` /
+``--miphoneos-version-min=``.
----------------
Nit: older versions of macOS or iOS


================
Comment at: docs/LanguageExtensions.rst:1281
+
+Before LLVM 5.0, when calling a function that exists only in the newest OS
+version, programmers had to carefully check if the function exists at runtime,
----------------
...in the OS that's newer than the target OS (as determined by the minimum deployment version), ..


================
Comment at: docs/LanguageExtensions.rst:1286
+Objective-C methods.  If such a check was missed, the program would compile
+fine, run fine on the new OS version, but crash on older OS versions.
+
----------------
NIT: run fine on newer systems, but crash on older systems.


================
Comment at: docs/LanguageExtensions.rst:1291
+with the new ``@available()`` keyword to assist with this issue.  If a function
+is called that exists on new OS versions while the minimum deployment version
+is older, then ``-Wunguarded-availability`` will fire:
----------------
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:


================
Comment at: docs/LanguageExtensions.rst:1303
+
+To fix the warning (and to make the call not crash on 10.11!), wrap it in
+``if(@available())``:
----------------
Nit: and to avoid the crash on macOS 10.11


================
Comment at: docs/LanguageExtensions.rst:1342
+``@available()`` is only available in Objective-C code.  To use the feature
+in C and C++ files, use the ``__builtin_available()`` spelling instead.
+
----------------
Nit: in C and C++ code


================
Comment at: docs/LanguageExtensions.rst:1347
+
+In rare cases, the availability annotation on an API might be overly
+conservative.  For example, ``[NSProcessInfo processInfo]`` secretly responds to
----------------
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)?


https://reviews.llvm.org/D35379