[SR-15572] [Swift-DocC] Support custom display names for frameworks

[ethan-kusters]

Previous ID	SR-15572
Radar	rdar://problem/86279414
Original Reporter	@ethan-kusters
Type	Improvement
Status	Resolved
Resolution	Done

Additional Detail from JIRA

Votes	0
Component/s	Swift-DocC
Labels	Improvement
Assignee	@d-ronnqvist
Priority	Medium

md5: c3fa5665e09635e8743f8f59ebc6b0c8

Issue Description:

Today Swift-DocC always renders a framework's more technical name as the title of the framework overview page. In many scenarios, developer's will likely want to customize this value when they're not limited by what characters are valid in the framework's actual name.

For example, the SwiftDocC framework, may prefer to render as "Swift DocC" or "Swift-DocC". Or maybe "ArgumentParser" would prefer to render as "Swift Argument Parser".

Swift-DocC should expose customization on the CLI and in documentation catalogs for a module's display name.

[ethan-kusters]

@swift-ci create

[swift-ci]

Comment by Waheed Afolabi (JIRA)

@d-ronnqvist I have assigned it to myself!

Could you please show me the direction to follow now!

[d-ronnqvist]

Great! I'll post a comment with more information later today or tomorrow.

[d-ronnqvist]

A important note

Since this is a user facing change with potentially new syntax, we would want to make a small pitch in the forums for the proposed solution (not the full evolution process, just a small post so that the community can discuss the user impact). I can help you with the pitch but the discussion is not going to conclude until sometime after the new year when people are back from vacation.

If you still want to work on this, I'll outline the design that I've been thinking of and directions for how to implement it. Just note that this design hasn't been discussed in the forums, so the final design may change.

If the pitch and discussion portion feel like to much for a first contribution I've also opened SR-15634 earlier today and left a comment with some directions of how that could be implemented.

My proposed design

The user facing changes that I've imagined here is to introduce a new @DisplayName directive that would be a child of the existing @Metadata directive. Developers would add this directive to customize the title that's displayed for a given module in the documentation extension for that module. For example:

# ``ArgumentParser``

@Metadata {
{{ @DisplayName("Swift Argument Parser")}}
{{}}}

Straightforward, type-safe argument parsing for Swift.
...

This would allow for per-page customization when a symbol's name isn't the preferred display name. (A framework's top level page represents the frameworks "module" symbol.

DocumentationExtension is an example of how such a directive could be implemented and the Metadata directive would also need to updated to parse that from its child content

With that information available on the documentation extension, when a DocumentationNode is initialized with a symbol and a documentation extension it would check if the documentation extension has specified a custom display name and set its name to a Name.conceptual(title🙂 instead of the Name.symbol(declaration🙂. It may also be necessary to do the same check for a custom display name in initializeSymbolContent(documentationExtension: engine:. I believe that only the node's name needs to change to control how the page's title.

MetadataTests has existing tests specific to how the the @Metadata directive parses its content.

This test in SemaToRenderNodeTests.swift could serve as a starting point for how to test the full flow of providing a custom display name in a directive in the documentation extension, verifying that that documentation node's name is correct, rendering that node and verifying that the render node also contains the right title (the render node's metadata hold the title for the page).

[d-ronnqvist]

Also, If you want to implement this but not do the pitch, then I can post a pitch for this sometime after the new year.

[swift-ci]

Comment by Waheed Afolabi (JIRA)

@d-ronnqvist Thanks for your time and providing this guidance.

I'd love to implement this, as well as make the pitch but I haven't done one.

I don't know how to, but I want to start doing it

After the new year is cool!

[swift-ci]

Comment by Waheed Afolabi (JIRA)

While trying to see how a pitch is done, I found this:

https://forums.swift.org/t/modify-accessors/31872

I see a pattern, however I am not sure if this particular one is too complex to study for the goal at hand, or if you have a simpler one you could point me to as a reference.

[d-ronnqvist]

Swift-DocC uses a slightly simplified pitch/proposal process compared to the broader Swift Evolution process.

Here are a few examples of previous pitches for Swift-DocC:

• https://forums.swift.org/t/improve-presentation-of-non-framework-documentation-sr-15434/53388

• https://forums.swift.org/t/extending-swift-docc-render-json-to-support-multi-language-symbols/52881

• https://forums.swift.org/t/extending-swift-docc-to-support-objective-c-documentation/53243

• https://forums.swift.org/t/support-hosting-docc-archives-in-static-hosting-environments/53572

This is how I would describe the current format:

• A brief description/summary of the problem.

• Motivation (optional): An explanation of what benefit will be provided by solving the problem. This can be left out if the benefit is clear from the problem description.

• Proposed Solution: A high level overview that describe the intended solution.

• Detailed Design (optional): A more in-depth description of the solution. This can be left out if most of the design is already described by the high level overview above.

• Alternatives Considered (optional): An even briefer description of any alternatives that were considered and their drawbacks compared to the proposed solution.

[d-ronnqvist]

waheedNowLovesSwift (JIRA User) I talked to some of my colleagues about this. We discussed two alternatives—one alternative was specifying the display name in the h1 heading and using a directive to associate the file with the symbol and the other alternative was using a different link syntax in the h1 heading—but we think that the @DisplayName directive is the better solution.

Unless you really want to write the pitch, I offering to write the pitch for this but leave the implementation to you. Pitching a design for an enhancement is above and beyond what we'd expect for a first time contribution.

[d-ronnqvist]

I will probably post a pitch for this sometime next week. After that we'll want to give the community at least a week to provide their feedback.

[d-ronnqvist]

I posted a proposal for this here https://forums.swift.org/t/support-customizing-the-display-name-for-symbol-documentation/55169

[d-ronnqvist]

waheedNowLovesSwift (JIRA User) I may try and implement this later this week or early next week.

[swift-ci]

Comment by Waheed Afolabi (JIRA)

@d-ronnqvist great to know you've done the proposal...

Is there a way I could work along, I seem blacked out on how to move!

[d-ronnqvist]

waheedNowLovesSwift (JIRA User) I've started working in this here but there are still a few pieces remaining if you want to work on that. Let me know and we'll figure our a way to collaborate on it.

The Directive turned out to be harder to implement than what I originally intended and I needed to make some swift-markdown changes here to support an initial argument without a label / name.

[d-ronnqvist]

This PR is merged now.