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

[Saleem Abdulrasool via Phabricator via cfe-commits]

compnerd marked 3 inline comments as done.
compnerd added inline comments.


================
Comment at: clang/docs/APINotes.rst:45
+Clang will search for API notes files next to module maps only when passed the
+``-fapinotes-modules`` option.
+
----------------
rsmith wrote:
> Can we add a hyphen between `api` and `notes` here? `-fapinotes` is a little hard to read.
Sure; we can always add a `-fapinotes-modules` as a silent alias for backwards compatibility.  I assume you would like the same for the rest of the options, and have made that change through out.


================
Comment at: clang/docs/APINotes.rst:187-190
+  - "N"onnull (``_Nonnull``)
+  - "O"ptional (``_Nullable``)
+  - "U"nspecified (``_Null_unspecified``)
+  - "S"calar (deprecated)
----------------
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.


================
Comment at: clang/docs/APINotes.rst:233-235
+  Note that the type is *not* parsed in the context where it will be used,
+  which means that macros are not available and nullability must be applied
+  explicitly (even in an ``NS_ASSUME_NONNULL_BEGIN`` section).
----------------
rsmith wrote:
> So what context is it parsed in? Below you have an `NSArray *` example; how do we do the lookup for `NSArray`?
A separate buffer is constructed where the annotations are processed.  During semantic analysis, the requested APINotes are processed and the attributes specified are applied to the declaration.


Repository:
  rG LLVM Github Monorepo

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

https://reviews.llvm.org/D88446