Add variants APIs for multi-language symbols #25
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
franklinsch
force-pushed
the
symbol-variants
branch
from
68ae9cd to
e62f992
Compare
Contributor
Author
|
@swift-ci please test |
Adds APIs for specifying different variants for fields of the Symbol API in support of documenting symbols that are available in multiple languages, for example Swift and Objective-C. rdar://83665056
Emits multi-language symbol data to render JSON. rdar://82967644
Since the SymbolDataVariants is now used beyond symbol APIs, this renames the type to something more generic. rdar://82967644
franklinsch
force-pushed
the
symbol-variants
branch
from
e62f992 to
de668ad
Compare
Contributor
Author
|
@swift-ci test |
QuietMisdreavus
approved these changes
Nov 4, 2021
Contributor
QuietMisdreavus
left a comment
QuietMisdreavus
left a comment
There was a problem hiding this comment.
Looks good, thanks!
| /// about the symbol. For example, if a symbol is available in multiple programming languages, the ``titleVariants`` property represents the title of the symbol | ||
| /// for each programming language it's available in. Use a ``SymbolDataVariantsTrait`` to access a specific variant. | ||
| /// | ||
| /// ## Topics |
Contributor
There was a problem hiding this comment.
Really thankful that you added documentation links for all the new fields!
3 tasks
ethan-kusters
added a commit
to ethan-kusters/swift-docc
that referenced
this pull request
Jan 11, 2023
Includes the following changes:
commit b1622a0a0b747740839511b1387289bcf1c64b19
Author: Ethan Kusters <[email protected]>
Date: Mon Jan 9 17:42:46 2023 -0800
Adds the `seeAlso` aside
“See Also” is a common kind of aside that folks parsing markdown
may wish to consider.
For Swift-DocC specifically, there is a lot of pre-DocC Swift
documentation content that uses this style of callout:
```
- SeeAlso:
```
In order to gracefully transition this content over to Swift-DocC
style asides, we should add support for them.
commit 87ae1a8fa9180b85630c7b41ddd5aa40ffc87ce3
Author: Ashley Garland <[email protected]>
Date: Tue Dec 6 20:23:49 2022 -0800
Adopt more snippets
Add snippets for the following areas:
- Parsing
- Querying
- Walkers, Rewriters, and Visitors
- Formatting
Add a link to the top-level page.
Add an article which inlines all of the snippets in one place for quick reference.
rdar://103054461
commit 3a631f4d4b0e9c80004b8555bcb629c898e8089f
Author: Tim Triemstra <[email protected]>
Date: Fri Dec 2 13:15:36 2022 -0800
Fixed the snippets support to use the new standard comment structure, and the @snippet references use the full path to the snippet file
commit 0d04722bafe7c6c29c485e4bdaa2235b879cc7e7
Author: Ashley Garland <[email protected]>
Date: Tue Mar 29 23:18:49 2022 -0700
Example usage of snippets for Swift Evolution
commit 7dd6c526c9184fd7fabdda592167f305727b515e
Author: Christian Selig <[email protected]>
Date: Tue Nov 29 12:42:21 2022 -0400
Add support for custom attributes (swiftlang#25)
rdar://96536586
ethan-kusters
added a commit
that referenced
this pull request
Jan 28, 2023
Includes the following changes:
commit b1622a0a0b747740839511b1387289bcf1c64b19
Author: Ethan Kusters <[email protected]>
Date: Mon Jan 9 17:42:46 2023 -0800
Adds the `seeAlso` aside
“See Also” is a common kind of aside that folks parsing markdown
may wish to consider.
For Swift-DocC specifically, there is a lot of pre-DocC Swift
documentation content that uses this style of callout:
```
- SeeAlso:
```
In order to gracefully transition this content over to Swift-DocC
style asides, we should add support for them.
commit 87ae1a8fa9180b85630c7b41ddd5aa40ffc87ce3
Author: Ashley Garland <[email protected]>
Date: Tue Dec 6 20:23:49 2022 -0800
Adopt more snippets
Add snippets for the following areas:
- Parsing
- Querying
- Walkers, Rewriters, and Visitors
- Formatting
Add a link to the top-level page.
Add an article which inlines all of the snippets in one place for quick reference.
rdar://103054461
commit 3a631f4d4b0e9c80004b8555bcb629c898e8089f
Author: Tim Triemstra <[email protected]>
Date: Fri Dec 2 13:15:36 2022 -0800
Fixed the snippets support to use the new standard comment structure, and the @snippet references use the full path to the snippet file
commit 0d04722bafe7c6c29c485e4bdaa2235b879cc7e7
Author: Ashley Garland <[email protected]>
Date: Tue Mar 29 23:18:49 2022 -0700
Example usage of snippets for Swift Evolution
commit 7dd6c526c9184fd7fabdda592167f305727b515e
Author: Christian Selig <[email protected]>
Date: Tue Nov 29 12:42:21 2022 -0400
Add support for custom attributes (#25)
rdar://96536586
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Bug/issue #, if applicable: rdar://83665056
Summary
Update the Symbol API to support variants. Each property has a
variantscounterpart property and the original properties have been updated to forward to the variants counterpart.The first commit just hardcodes accesses to use the Swift variant so that there are no user-facing changes.
Then, the second commit adds support for emitting multi-language symbol data:
VariantCollection+Symbol.swiftfile contains initializers that create render node variant models(
VariantCollection) from symbol data (DocumentationDataVariants).RenderNodeTranslatorhas been updated to consume all the symbols' variants and populaterender node
VariantCollectionproperties.RenderNode.primaryContentSectionsarray has beenrefactored to subtypes of the new
RenderSectionTranslatorprotocol, for clarity.JSONPatchinfrastructure now supports theaddoperation, which was needed for valuesthat are not present in the default render node's fields, but for which we have overrides for.
SymbolDataVariantswas renamed toDocumentationDataVariantssince the typeis now used beyond symbol data, e.g., as the return value of
LinkTitleResolver.title(for:).Dependencies
None.
Testing
There should be no user-facing changes yet, since this doesn't bring support for ingesting Objective-C symbol graph files yet.
Checklist
./bin/testscript and it succeeded