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

[Richard Smith - zygoloid via Phabricator via cfe-commits]

rsmith added a comment.

Broadly, it seems reasonable to me for Clang to support this. I have no major concerns with the overall approach here, and it seems like you already have sufficient implementation experience with this approach to know that it's going to work out well in practice. I'm happy that all of the points in http://clang.llvm.org/get_involved.html for Clang extensions are covered -- or will be covered by the work to implement this.



================
Comment at: clang/docs/APINotes.rst:5-12
+**The Problem:** You have headers you want to use, but you also want to add
+extra information to some of the APIs. You don't want to put that information
+in the headers themselves --- perhaps because you want to keep them clean for
+other clients, or perhaps because they're from some open source project and you
+don't want to modify them at all.
+
+**Incomplete solution:** Redeclare all the interesting APIs in your own header
----------------
"API" should generally be used only as an uncountable noun. If you mean something more concrete here, such as "a function, method, type, ...", then saying that would be better, since "API" can be interpreted as meaning an individual such entity or a collection of such entities, depending on the reader.


================
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.
+
----------------
Can we add a hyphen between `api` and `notes` here? `-fapinotes` is a little hard to read.


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


================
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).
----------------
So what context is it parsed in? Below you have an `NSArray *` example; how do we do the lookup for `NSArray`?


================
Comment at: clang/docs/APINotes.rst:273
+  Used for ``NSError`` code enums. The value is the name of the associated domain
+  ``NSString`` constant; an empty string ("") means the enum is a normal enum
+  rather than an error code.
----------------



Repository:
  rG LLVM Github Monorepo

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

https://reviews.llvm.org/D88446