[PATCH] D88446: docs: add documentation describing API Notes

[Saleem Abdulrasool via Phabricator via cfe-commits]

compnerd marked an inline comment as done.
compnerd added inline comments.


================
Comment at: clang/docs/APINotes.rst:216
+    Due to a compiler bug, 'NullabilityOfRet' may change nullability of the
+    parameters as well (rdar://30544062). Avoid using it and instead use
+    'ResultType' and specify the return type along with a nullability
----------------
hlopko wrote:
> Could we get more context from the Apple bug tracker? Depending on the details it might be reasonable to drop NullabilityOfRet attribute completely, or more precisely document when it should be used.
The bug is that Nullability and Type on Parameters entries don’t really compose. Consider the following note:

```
      NullabilityOfRet: N
      Parameters:
      - Position: 1
        Nullability: O
        Type: 'NSDictionary<NSString *, id> *'
```

on a method: this parameter won’t be treated as optional. Effectively, you need to write the _Nullable on the type because the Nullability entry is ignored.

I think that fixing this later is preferable rather than earlier to ensure that we at least have a unified starting point where clang and Swift can co-evolve.  If we try to do that while upstreaming, it will make everything far more difficult because you have to coordinate over multiple (3+) repositories.


Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D88446/new/

https://reviews.llvm.org/D88446