Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[SR-15317] [Swift-DocC] Emit a warning for a "See Also" task group within a Topics section. #57639

Closed
ethan-kusters opened this issue Oct 13, 2021 · 1 comment
Assignees
Labels
bug A deviation from expected or documented behavior. Also: expected but undesirable behavior. diagnostics QoI Bug: Diagnostics Quality of Implementation good first issue Good for newcomers

Comments

@ethan-kusters
Copy link
Contributor

Previous ID SR-15317
Radar rdar://60684559
Original Reporter @ethan-kusters
Type Bug
Status Resolved
Resolution Done
Additional Detail from JIRA
Votes 0
Component/s Swift-DocC
Labels Bug, DiagnosticsQol, StarterBug
Assignee @Kyle-Ye
Priority Medium

md5: 963ca050244e96619e8c563b137ddc6e

Issue Description:

It's easy to accidentally write a "See Also" section as part of a Topics section (like the following) instead of as it's own second-level heading like DocC expects:

# ``ModuleName/SymbolName``

Symbol overview.

## Topics

### First Task Group

- ``ChildSymbol``

### See Also

- ``RelatedSymbol``

However, DocC requires See Also sections to be written as second-level headings beneath a Topics section, not as subsections of Topics sections. DocC should emit a warning with a fixit upon encountering this. In this case, the fixit would update the example to the following:

# ``ModuleName/SymbolName``

Symbol overview.

## Topics

### First Task Group

- ``ChildSymbol``

## See Also

- ``RelatedSymbol``

@Kyle-Ye
Copy link
Collaborator

Kyle-Ye commented Oct 16, 2021

Pull request in apple/swift-docc#8

@swift-ci swift-ci transferred this issue from apple/swift-issues Apr 25, 2022
@shahmishal shahmishal added diagnostics QoI Bug: Diagnostics Quality of Implementation and removed DiagnosticsQol labels Apr 26, 2022
This issue was closed.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
bug A deviation from expected or documented behavior. Also: expected but undesirable behavior. diagnostics QoI Bug: Diagnostics Quality of Implementation good first issue Good for newcomers
Projects
None yet
Development

No branches or pull requests

3 participants