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

Thu Oct 1 23:43:59 PDT 2020

hlopko accepted this revision.
hlopko added a comment.
This revision is now accepted and ready to land.

Thanks for pushing this forward!

Current proposal seems to be only dealing with annotating ObjC for Swift, but API notes seem like a feature that would be useful for other languages as well. I briefly chatted with gribozavr and we concluded that if the need arises, the current design should be extensible to e.g. C++ (one of the bigger problems being how to name C++ function/overload sets).

================
Comment at: clang/docs/APINotes.rst:187-190
+  - "N"onnull (``_Nonnull``)
+  - "O"ptional (``_Nullable``)
+  - "U"nspecified (``_Null_unspecified``)
+  - "S"calar (deprecated)
----------------
compnerd wrote:
> rsmith wrote:
> > Is it important that these are single letters? Spelling out the name in full (as you do for other enumerated values like `MethodKind` and `PropertyKind`) would seem a little more readable. (We could accept the single-letter forms as aliases.)
> I don't think that they be single letters is important.  As long as we have the compatibility aliases, I think it should be fine to support the fully spelt out versions, as the compatibility is needed for existing APINotes.
+1, this is the only attribute that is abbreviated.

================
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
----------------
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.

Repository:
  rG LLVM Github Monorepo

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

https://reviews.llvm.org/D88446