Add a helper function for rendering symbol declarations as HTML #1384
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
rdar://163326857
Contributor
Author
|
@swift-ci please test |
3 tasks
heckj
approved these changes
Dec 5, 2025
patshaughnessy
approved these changes
Dec 6, 2025
Contributor
patshaughnessy
left a comment
patshaughnessy
left a comment
There was a problem hiding this comment.
Nice work 👍 Thanks for breaking these up into separate PRs...
| let fragmentsByLanguage = RenderHelpers.sortedLanguageSpecificValues(fragmentsByLanguage) | ||
|
|
||
| guard goal == .richness else { | ||
| // If the goal is conciseness, display only the primary language's plain text declaration |
Contributor
There was a problem hiding this comment.
See my comment in #1382 - can you explain why the concise version only displays info about the primary language? Maybe paste 2 examples for richness and conciseness above in the doc comments and then a quick sentence about why the concise version is sooo concise :)
| return .element(named: "pre", children: plainTextDeclaration) | ||
| } | ||
|
|
||
| let declarations: [XMLElement] = if fragmentsByLanguage.count == 1 { |
Contributor
There was a problem hiding this comment.
Reading this pattern in three or four functions now makes me wonder if you could extract the general behavior into a single place, and use a protocol, closure or some other means of calling the individual functions like _declarationTokens or _singleTaskGroupElements but maybe that would be difficult and not worth the effort?
Contributor
Author
There was a problem hiding this comment.
So far I don't feel that a clear enough pattern has emerged to know what abstraction to add, if any.
In the places so far, the common structure is a simply if count == 1 {...} else {...} and it would likely be hard to beat the readability and explicitness of that in an abstraction.
Contributor
Author
There was a problem hiding this comment.
So far I'm feeling that it's probably the caller's side (rather than these implementations) that would benefit from a helper function to perform some common work.
- Only includes the primary language - Joins the declaration fragments into a single string
Contributor
Author
|
@swift-ci please test |
3 tasks
d-ronnqvist
added a commit
to d-ronnqvist/swift-docc
that referenced
this pull request
Dec 17, 2025
…tlang#1384) * Add a helper function for rendering symbol declarations as HTML rdar://163326857 * Add code comments to describe why the concise declaration: - Only includes the primary language - Joins the declaration fragments into a single string
d-ronnqvist
added a commit
that referenced
this pull request
Dec 17, 2025
…1402) * Add a new target for rendering Markdown content into static HTML (#1369) * Add a new target for rendering content into static HTML rdar://163326857 * Include documentation comments with examples for the various `visit(_:)` methods. * Document what a `LinkedAsset` represents * Add code comments to explain how the inline HTML markup is parsed * Don't lowercase anchors for self-referencing headings * Avoid nested scopes when switching over names * Add a code comment about what an "autolink" is * Add a helper function for rendering availability information as HTML (#1376) rdar://163326857 * Add a helper function for rendering page breadcrumbs as HTML (#1378) * Add a helper function for rendering page breadcrumbs as HTML rdar://163326857 * Apply wording suggestion in documentation comment Co-authored-by: Joseph Heck <j_heck@apple.com> --------- Co-authored-by: Joseph Heck <j_heck@apple.com> * Add a helper function for rendering a parameters section as HTML (#1377) * Add a helper function for rendering a parameters section as HTML rdar://163326857 * Apply wording suggestions in documentation comments Co-authored-by: Pat Shaughnessy <pat_shaughnessy@apple.com> Co-authored-by: Joseph Heck <j_heck@apple.com> * Add TODO comment about a debug assertion for the parameter name order --------- Co-authored-by: Pat Shaughnessy <pat_shaughnessy@apple.com> Co-authored-by: Joseph Heck <j_heck@apple.com> * Add tests for parsing of inline HTML when rendering markdown as HTML (#1379) * Add test about parsing inline HTML except for comments * Extract inner HTML parsing code into a private function * Fix minor spelling in code comment Co-authored-by: Pat Shaughnessy <pat_shaughnessy@apple.com> --------- Co-authored-by: Pat Shaughnessy <pat_shaughnessy@apple.com> * Add a helper function for rendering a returns sections as HTML (#1381) * Add a helper function for rendering a returns sections as HTML rdar://163326857 * Minor phrasing updates to the parameter section helper's documentation * Add new source file to Windows CMake file list * Correct grammar in documentation comments Co-authored-by: Pat Shaughnessy <pat_shaughnessy@apple.com> --------- Co-authored-by: Pat Shaughnessy <pat_shaughnessy@apple.com> * Add a helper function for rendering symbol declarations as HTML (#1384) * Add a helper function for rendering symbol declarations as HTML rdar://163326857 * Add code comments to describe why the concise declaration: - Only includes the primary language - Joins the declaration fragments into a single string * Add a helper function for rendering a Topics/SeeAlso section as HTML (#1382) * Add a helper function for rendering a Topics/SeeAlso section as HTML rdar://163326857 * Add more code comments and internal documentation comments * Very slightly correct the test data * Minimally integrate per-page HTML content into each "index.html" file (#1383) * Minimally integrate per-page HTML content into each "index.html" file rdar://163326857 * Extract some common code into private helpers * Move a few common checks into the new private helpers * Add a helper function for rendering a discussion section as HTML (#1388) * Add a helper function for rendering a discussion section as HTML rdar://163326857 * Integrate the discussion section in the HTML renderer * Include Mentioned In and Relationships sections in the HTML output (#1391) * Include more content in the HTML output (#1390) * Include more page content in the HTML output * Also add deprecation summaries to the HTML output --------- Co-authored-by: Joseph Heck <j_heck@apple.com> Co-authored-by: Pat Shaughnessy <pat_shaughnessy@apple.com>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 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://163326857
Summary
This is another slice of #1366
It adds a helper function to the
DocCHTML/MarkdownRendererto render a symbol's declaration 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