Add a helper function for rendering a Topics/SeeAlso section as HTML #1382
Conversation
|
@swift-ci please test |
|
|
||
| /// Creates a grouped section with a given name, for example "topics" or "see also" that describes and organizes groups of related API. | ||
| /// | ||
| /// If each language representation of the API has their own language-specific parameters, pass each language representation's parameter information. |
There was a problem hiding this comment.
| /// If each language representation of the API has their own language-specific parameters, pass each language representation's parameter information. | |
| /// If each language representation of the API has their own language-specific set of parameters, pass the parameter information for each language representation. |
There was a problem hiding this comment.
And: has their -> has its
| /// If each language representation of the API has their own language-specific parameters, pass each language representation's parameter information. | ||
| /// | ||
| /// If the API has the _same_ parameters in all language representations, only pass the parameters for one language. | ||
| /// This produces a "parameters" section that doesn't hide any parameters for any of the languages (same as if the symbol only had one language representation) |
There was a problem hiding this comment.
| /// This produces a "parameters" section that doesn't hide any parameters for any of the languages (same as if the symbol only had one language representation) | |
| /// This produces a "parameters" section that doesn't hide any parameters for any of the languages (the same as if the symbol only had one language representation). |
|
|
||
| let renderer = makeRenderer(goal: goal, elementsToReturn: elements) | ||
| let expectedSectionID = expectedGroupTitle.replacingOccurrences(of: " ", with: "-") | ||
| let groupedSection = renderer.groupedSection(named: expectedGroupTitle, groups: [ |
There was a problem hiding this comment.
Since you've included the OCC representation with alternate parameters above, could we also include (or make a second set of asserts) that show the expected output when the language is ObjC?
There was a problem hiding this comment.
What language is specified here doesn't impact the output. This is testing the same task groups in all languages but the names/subheadings of referenced symbols have difference names in each language. You can see in the "rich" test assertion that the the output contains both titles as <code class="swift-only"> and <code class="occ-only"> elements inside the same anchor.
| /// | ||
| /// If the API has the _same_ parameters in all language representations, only pass the parameters for one language. | ||
| /// This produces a "parameters" section that doesn't hide any parameters for any of the languages (same as if the symbol only had one language representation) | ||
| func groupedSection(named sectionName: String, groups taskGroups: [SourceLanguage: [TaskGroupInfo]]) -> [XMLNode] { |
There was a problem hiding this comment.
The comments above are talking about a parameters section. Should we update the comments to describe the task group section this function returns?
There was a problem hiding this comment.
Good catch. I updated these comments in 2931e98
| let fragmentsByLanguage = RenderHelpers.sortedLanguageSpecificValues(fragmentsByLanguage) | ||
| items = if fragmentsByLanguage.count == 1 { | ||
| [ _symbolSubheading(fragmentsByLanguage.first!.value, languageFilter: nil) ] | ||
| } else if goal == .conciseness, let fragments = fragmentsByLanguage.first?.value { |
There was a problem hiding this comment.
Are we ignoring the second (and subsequent languages) here for concise mode? Please explain why with a comment.
There was a problem hiding this comment.
I added a short comment that describes this in 2931e98
| ]) | ||
| } | ||
|
|
||
| private func _symbolSubheading(_ fragments: [LinkedElement.SymbolNameFragment], languageFilter: SourceLanguage?) -> XMLElement { |
There was a problem hiding this comment.
An HTML example here or above might be nice; this is getting a bit complex.
|
@swift-ci please test |
3 participants
Bug/issue #, if applicable: rdar://163326857
Summary
This is another slice of #1366
It adds a helper function to the
DocCHTML/MarkdownRendererto render "topics" and "see also" sections as HTML.Dependencies
None.
Testing
Nothing in particular for this PR. It only adds an internal helper function. See #1366 for how it eventually does get used.
Checklist
Make sure you check off the following items. If they cannot be completed, provide a reason.
./bin/testscript and it succeeded