[docs] Add documentation for underscored attributes.

[varungandhi-apple]

I figured I should at least start a PR instead of being lazy.

Fixes rdar://65258964.

[varungandhi-apple]

cc @benrimmington in case you have any suggestions.

[benrimmington]

Are there any underscored Objective-C attributes used by the Clang importer?

[davidungar]

Great idea to document these! Are there pointers to the document in the code where it implements these?

[varungandhi-apple]

No, there are no such links as it's likely they would break when code gets moved around. Searching by the attribute strings and related types that come up seems to give good enough results, I think. For certain attributes, they are not implemented in a single place, they affects lots of things, so pointing to 1-2 places could potentially be misleading.

Are there specific attributes that you think would benefit from this treatment?

[varungandhi-apple]

Are there any underscored Objective-C attributes used by the Clang importer?

Do you mean things like __attribute__((__swift_attr__("@MainActor")))? That does have an alternate spelling __attribute__((swift_attr("@MainActor"))) which I think should be accepted...

[davidungar]

No, there are no such links as it's likely they would break when things get moved around. Searching by the attribute strings and related types that come up seems to give good enough results, I think. For certain attributes, they are not implemented in a single place, they affects lots of things, so pointing to 1-2 places could potentially be misleading.

Are there specific attributes that you think would benefit from this treatment?

Sorry--I wrote "link" but all I meant was a comment, say where these are parsed that would refer the reader to the document.

Good question about attributes. The one I hit was _spi, which you may already have documented.

Again, I'm really glad you are taking this on. It would have helped me to have this documentation.

[varungandhi-apple]

Well, you said pointers -- which I mis-interpreted as links. With comments, I'm not sure of what the value-add is over searching... Consider the example of _spi. In Attr.def, it's named SPIAccessControl, searching for that gives a bunch of hits, including one in ParseDecl.cpp showing where it is parsed. In Module.cpp, there are a bunch of hits showing where it is used for filtering out declarations. And so on.

That said, I'm not super tied to not having links/comments. I'll try to gather feedback from other people to see what they think about the additional value of having comments about implementation.

I've added some notes for @_spi, but happy to add more details if you think something is unclear or could do with more explanation.

[benrimmington]

Are there any underscored Objective-C attributes used by the Clang importer?

Do you mean things like __attribute__((__swift_attr__("@MainActor")))? That does have an alternate spelling __attribute__((swift_attr("@MainActor"))) which I think should be accepted...

I should have written undocumented Clang attributes, but I don't know if any exist, or if this is the right place to put them.

(swift_attr is documented at https://clang.llvm.org/docs/AttributeReference.html).

[davidungar]

Well, you said pointers -- which I mis-interpreted as links. With comments, I'm not sure of what the value-add is over searching... Consider the example of _spi. In Attr.def, it's named SPIAccessControl, searching for that gives a bunch of hits, including one in ParseDecl.cpp showing where it is parsed. In Module.cpp, there are a bunch of hits showing where it is used for filtering out declarations. And so on.

That said, I'm not super tied to not having links/comments. I'll try to gather feedback from other people to see what they think about the additional value of having comments about implementation.

I've added some notes for @_spi, but happy to add more details if you think something is unclear or could do with more explanation.

Sounds good. In my case, I don't always think of searching the docs folder when I am reading the code. And then, there are a lot of docs in there. But if a search in Xcode for "_spi" finds your document, then a comment adds less.

[varungandhi-apple]

I should have written undocumented Clang attributes, but I don't know if any exist, or if this is the right place to put them.

If there are undocumented Clang attributes (I don't recall any but in case you come up with something), IMO that should be a bug-fix in Clang's documentation, not adding those here (because it's less likely someone will search here).

[CodaFi]

Some additional entries.

[atrick]

Looks good so far. I added comments wherever I felt qualified to do so.

[xwu]

Really excited about this. Learned a few things reading it! I'm made a few grammar/style-related suggestions, but there are also some substantive additions and suggestions thrown in.

[xwu]

It was really cool to see a description of why @_disfavoredOverload was designed. Similarly here, reference could be made to its (earliest?) use in implementing synthesized conformances to Equatable and Hashable.

[beccadax]

It may not have come across, but I gave background on @_disfavoredOverload to try to illustrate when it should be used (i.e. to work around a known defect in overload resolution that can't be immediately fixed without breaking source, and particularly to work around that specific bug with literals). If that seemed like cool background info rather than a usage guideline, maybe it should be rephrased.

[xwu]

How about, "Marks a declaration that is not an override of another, required when compiling with the -warn-implicit-overrides flag, which warns when a protocol restates a requirement from another protocol that it refines without annotating the declaration with either override or @_nonoverride."

[varungandhi-apple]

Updated wording.

[varungandhi-apple]

Fixed merge conflict; this is ready for ~final review, in case anyone has other comments. Barring that, I will land this PR on Monday next week.

[varungandhi-apple]

@swift-ci smoke test

[varungandhi-apple]

@swift-ci smoke test Linux