Hi all,
I'd like to propose a new documentation syntax to allow for customization of a symbol's display name.
This work would resolve [SR-15572] [Swift-DocC] Support custom display names for frameworks.
Motivation
When Swift-DocC builds documentation for a target—for example a framework, app, or command-line tool—the symbol that represents that target's module becomes the root of documentation under which all other symbols and articles are grouped.
As with all other symbols, the symbol name is used as the title of that page, the title of links to that page, and the title of that page in the breadcrumbs and navigation hierarchy.
Developers may prefer another conceptual title for the target's root documentation page. For example, the people working on the SwiftDocC framework may prefer the display name "Swift DocC" or "Swift-DocC", the people working on the ArgumentParser framework may prefer the display name "Swift Argument Parser", or the people working on an app may prefer the display name of the app—which may contain characters that's not present in the app's module name.
Proposed Solution
Add a new @DisplayName directive as an optional child of the existing @Metadata directive. Developers can add this directive in the documentation extension file to customize the symbol's display name. For example:
# ``ArgumentParser``
@Metadata {
@DisplayName("Swift Argument Parser")
}
Straightforward, type-safe argument parsing for Swift.
...
This allows for per-page customization when a symbol's name isn't the preferred display name.
Detailed Design
A customized symbol display name will override the symbol's name everywhere that it's currently displayed (see "Motivation" above for list of places). This mean that the module name will no longer appear in the documentation unless it is explicitly authored. For documentation about apps or command-line tools the module name has very limited value but for documentation about frameworks or libraries the module name is what consumers of the framework need to write when importing the framework. We trust developers to write setup documentation that mention the name of the module to import if they deem that necessary but hope to make this type of setup documentation more convenient to write in the future. See "Future Directions" below.
The new @DisplayName directive will have two arguments:
- a required display name value
- an optional
stylevalue that's either "conceptual" (the default) or "symbol"
When the style is "conceptual", the DocumentationNode that Swift-DoccC creates for the symbol with the customized display name will have a Name.conceptual(title:) value instead of a Name.symbol(declaration:) value. This means that symbol links to that symbol will render without a monospaced text style.
While this new directive is mostly meant to allow for the customization of module symbol pages, we propose that all symbol pages support it to give the developers the extra flexibility. Articles will not support this directive since articles already have a syntax, the level 1 heading, for specifying the page's title. Adding a @DisplayName directive in an article will result in a warning and the title from the directive will be ignored.
When building documentation without a documentation catalog (.docc directory) but passing command line arguments to docc providing a custom display name (--fallback-display-name) and symbol graph files for a single module (--additional-symbol-graph-dir) then Swift-DocC will leverage these changes to customize the display name of the module symbol's page.
Alternatives Considered
Instead of adding this directive to customize the display name (and using the level 1 heading to associate the documentation extension with the symbol) we considered doing the opposite; adding a new directive to associate a documentation extension file with a directive and use the level 1 heading to customize the title.
While both alternatives use the level 1 heading for one task and a directive for the other task, we prefer the conceptual task of "customizing the display name of a symbol" compared to the task of "customizing the symbol association of an article" and believe that developers are more likely to phrase the problem in terms of "how can I customize the title of this page" and therefore will find the @DisplayName solution more straight forward.
We also considered broader design changes to the symbol link syntax (symbol paths surrounded by double back-ticks) to support specifying a title but felt that the added complexity and impact of that change was too great compared to simpler solutions.
Future Directions
In the future we would like to make it more convenient to write common types of setup documentation; for example how to add the documented library as a dependency to the consumer's Swift package manifest. These improvements are out of scope for this display name enhancement.