introduce a `@_documentation(...)` attribute to influence SymbolGraphGen #60242

QuietMisdreavus · 2022-07-26T14:13:14Z

Resolves rdar://79049241

This PR introduces a new attribute, @_documentation(...), that influences how SymbolGraphGen handles the symbol it's attached to. There are two forms of this attribute:

@_documentation(visibility: ...) treats the symbol as the given access level in the symbol graph, allowing you to hide a technically-public implementation detail from public documentation, or reveal a symbol with an underscored name that would otherwise be hidden.
@_documentation(metadata: ...) adds an arbitrary identifier to the symbol's "metadata" field, which can then be handled by other tooling.

This PR also fixes a pre-existing issue where symbols that were declared internal in a re-exported module would be included in the symbol graph if it was being requested with an internal access level, and similarly for anything below public.

QuietMisdreavus · 2022-07-26T14:13:25Z

@swift-ci Please test

include/swift/AST/Module.h

QuietMisdreavus · 2022-08-04T20:11:48Z

Based on discussion in this Swift Forums thread, i've pushed up a couple commits that change how the attribute works. Instead of a single @_nodoc attribute, there is now a general-purpose @_documentation(...) attribute that adds an arbitrary "documentation category" to the symbol. This is then read for two special-case categories: underscored treats the symbol as having an underscored name, hiding it from symbol graphs and docs by default; and ignoreUnderscored does the opposite, taking an underscored symbol and lifting it to its declared visibility (instead of internal), allowing public underscored symbols to appear in public docs.

QuietMisdreavus · 2022-08-04T20:11:57Z

@swift-ci Please test

QuietMisdreavus · 2022-08-10T17:16:52Z

Based on further discussion on the forums, the @_documentation attribute now has the following structure:

@_documentation(visibility: <level>) forces the symbol to act like it has the given access level in symbol graphs and documentation, allowing you to override an underscored name or treat a symbol like an internal one if it's only public for implementation-detail reasons.
@_documentation(metadata: ...) adds the given identifier to the symbol graph as a new "metadata" field. This can be used to add arbitrary information to a symbol that can be processed by later tooling.

QuietMisdreavus · 2022-08-10T17:16:57Z

@swift-ci Please test

franklinsch · 2022-08-11T08:13:54Z

docs/ReferenceGuides/UnderscoredAttributes.md

@@ -117,6 +117,27 @@ extension Text {
 }
 ```

+## `@_documentation(metadata: ...)`


I assume the value of the metadata parameter is just a string that be specified with or without quotes?

Right now it can only be an identifier, but i could see about making it a quoted string as well.

If it's a string in quotes, developers could stick in useful metadata like JSON, CSV, or hex encoded images which would be fun 👌🏼

franklinsch · 2022-08-11T08:14:46Z

include/swift/AST/Attr.h

@@ -2226,6 +2226,28 @@ class BackDeployAttr: public DeclAttribute {
  }
 };

+/// The `@_documentation(...)` attribute, used to note a "category" for a


Is the term "category" still correct given the latest changes?

It's not, good catch 😅

franklinsch · 2022-08-11T08:17:20Z

docs/ReferenceGuides/UnderscoredAttributes.md

+Adds "documentation metadata" to the symbol. The identifier in the attribute is
+added to the symbol graph in the `"metadata"` field of the symbol. This can be
+used to add an arbitrary grouping or other indicator to symbols for use in
+documentation.


Are you able to specify multiple @_documentation(metadata: …) attributes for the same declaration?

I'm not sure; i'll have to check. Offhand, i think the answer is "no" because of checks for duplicate attributes, but i'm not confident about it.

QuietMisdreavus · 2022-08-22T17:11:27Z

I've rebased onto the latest main, and squashed down the first few commits to discard the history of the initial implementation (which made rebasing much easier). I also added a tweak to allow quoted strings as doc metadata.

@swift-ci Please test

QuietMisdreavus · 2022-08-23T21:25:03Z

@swift-ci Please test

QuietMisdreavus · 2022-09-01T21:20:05Z

Rebased to resolve merge conflicts.

@swift-ci Please test

rdar://79049241

QuietMisdreavus · 2022-09-06T15:32:11Z

@swift-ci Please test

QuietMisdreavus requested review from DougGregor and franklinsch July 26, 2022 14:13

franklinsch reviewed Jul 26, 2022

View reviewed changes

include/swift/AST/Module.h Outdated Show resolved Hide resolved

QuietMisdreavus changed the title ~~introduce a @_nodoc attribute to hide symbols from the symbol graph~~ introduce a @_documentation(...) attribute to add "documentation categories" Aug 4, 2022

QuietMisdreavus force-pushed the QuietMisdreavus/nodoc-attr branch from 569bd2f to 7d9551c Compare August 10, 2022 17:14

QuietMisdreavus changed the title ~~introduce a @_documentation(...) attribute to add "documentation categories"~~ introduce a @_documentation(...) attribute to influence SymbolGraphGen Aug 10, 2022

franklinsch approved these changes Aug 11, 2022

View reviewed changes

QuietMisdreavus force-pushed the QuietMisdreavus/nodoc-attr branch from 1461391 to be76de2 Compare August 22, 2022 17:10

franklinsch approved these changes Aug 23, 2022

View reviewed changes

QuietMisdreavus force-pushed the QuietMisdreavus/nodoc-attr branch from be76de2 to 955beff Compare September 1, 2022 21:19

QuietMisdreavus added 3 commits September 6, 2022 09:31

add @_documentation(...) attribute to influence SymbolGraphGen

ccbac9d

rdar://79049241

review: reword comment for DocumentationAttr

7be5ad0

take a quoted string in @_documentation(metadata:)

cc55f0e

QuietMisdreavus force-pushed the QuietMisdreavus/nodoc-attr branch from 955beff to cc55f0e Compare September 6, 2022 15:31

QuietMisdreavus merged commit f674b47 into main Sep 6, 2022

QuietMisdreavus deleted the QuietMisdreavus/nodoc-attr branch September 6, 2022 20:12

tgrapperon mentioned this pull request Oct 5, 2022

ReducerProtocol pointfreeco/swift-composable-architecture#1283

Merged

hassila mentioned this pull request Feb 24, 2023

docs: use DocC for the documentation ordo-one/package-benchmark#63

Merged

5 tasks

orchetect mentioned this pull request Mar 2, 2023

Support excluding symbols swiftlang/swift-docc#406

Open

carson-katri mentioned this pull request Mar 9, 2023

Generate documentation for internal and SPI types liveview-native/liveview-client-swiftui#470

Merged

QuietMisdreavus mentioned this pull request Mar 13, 2023

add AST printer support for _documentation attribute #64326

Merged

introduce a @_documentation(...) attribute to influence SymbolGraphGen #60242

introduce a @_documentation(...) attribute to influence SymbolGraphGen #60242

Uh oh!

Conversation

QuietMisdreavus commented Jul 26, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

QuietMisdreavus commented Jul 26, 2022

Uh oh!

Uh oh!

QuietMisdreavus commented Aug 4, 2022

Uh oh!

QuietMisdreavus commented Aug 4, 2022

Uh oh!

QuietMisdreavus commented Aug 10, 2022

Uh oh!

QuietMisdreavus commented Aug 10, 2022

Uh oh!

franklinsch Aug 11, 2022

Choose a reason for hiding this comment

Uh oh!

QuietMisdreavus Aug 11, 2022

Choose a reason for hiding this comment

Uh oh!

icanzilb Sep 7, 2022

Choose a reason for hiding this comment

Uh oh!

franklinsch Aug 11, 2022

Choose a reason for hiding this comment

Uh oh!

QuietMisdreavus Aug 11, 2022

Choose a reason for hiding this comment

Uh oh!

franklinsch Aug 11, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

QuietMisdreavus Aug 11, 2022

Choose a reason for hiding this comment

Uh oh!

QuietMisdreavus commented Aug 22, 2022

Uh oh!

QuietMisdreavus commented Aug 23, 2022

Uh oh!

QuietMisdreavus commented Sep 1, 2022

Uh oh!

QuietMisdreavus commented Sep 6, 2022

Uh oh!

Uh oh!

introduce a `@_documentation(...)` attribute to influence SymbolGraphGen #60242

introduce a `@_documentation(...)` attribute to influence SymbolGraphGen #60242

QuietMisdreavus commented Jul 26, 2022 •

edited

Loading

franklinsch Aug 11, 2022 •

edited

Loading