DocC documentation catalogs support several Info.plist keys that control compilation behavior: bundle identity, default availability, code listing language, module kind, and experimental feature flags. These keys are not currently documented in the DocC documentation catalog, making them difficult to discover without reading the source.
The supported keys can be found by reading DocumentationBundle+Info.swift and related files, but DocC users shouldn't need to do that.
Proposed Addition
Add a documentation page to Sources/docc/DocCDocumentation.docc covering all supported keys.
Keys Identified in Source
Required
Key
Description
CFBundleDisplayName
The display name of the documentation bundle. Used as the module landing page title. CLI fallback: --fallback-display-name
CFBundleIdentifier
A reverse-DNS bundle identifier (e.g. com.example.MyLib). Scopes symbol links and cross-documentation references. Derives from CFBundleDisplayName if absent. CLI fallback: --fallback-bundle-identifier
Optional
Key
Description
CDDefaultCodeListingLanguage
Default syntax highlighting language for code blocks without an explicit language tag (e.g. swift). CLI fallback: --default-code-listing-language
CDDefaultModuleKind
The kind label for the top-level module symbol (e.g. Framework, SDK, Package). Defaults to Framework. CLI fallback: --fallback-default-module-kind
CDAppleDefaultAvailability
Default platform availability for symbols without an explicit @available annotation, per module. Accepts version strings or unavailable. No CLI fallback.
CDExperimentalFeatureFlags(experimental)
Dictionary of opt-in experimental features. Currently supports ExperimentalOverloadedSymbolPresentation and ExperimentalCodeBlockAnnotations. No CLI fallback.
Motivation
Better visibility for DocC users who configure catalogs manually or integrate DocC into custom tooling. These keys are already supported, they just need to be surfaced.
I'm happy to open a PR with the documentation page if there's interest.
I don't think it's necessary to have a proposal or pitch about writing more documentation but we can use this thread to talk about what that documentation would include and where (on what page) it makes sense to include it.
I tend to like documentation that surfaces relevant information in contextually appropriate places. This can help the reader find information that they didn't know they should have been looking for.
For example; we could document the CDDefaultCodeListingLanguage key as an aside in the existing documentation about writing code listings. In that context, the documentation could make the reader aware that if most (or all) of their code listings is in the same language, they can specify that language identifier once in the Info.plist instead of specifying it on the opening "fence" line of each code block. This key can also be used to support syntax highlighting in "indented" code blocks (as opposed to "fenced" code blocks) which don't have a Markdown syntax for specifying the source language identifier.
Similarly, I could imagine that we could document the CDDefaultModuleKind key either in the existing documentation about customizing the landing page or in the existing page about the @TitleHeading directive which is also can be used to customize the same on-page element for articles.
The other keys get more complicated.
Regarding CDAppleDefaultAvailability; It's always preferred to use in-source attributes (like @available or API_AVAILABLE) to specify availability information over using any documentation-only annotation. For this reason; the general advice for CDAppleDefaultAvailability would be to not use it and instead specify the availability using in-source attributes instead.
Regarding CDExperimentalFeatureFlags; This key in itself isn't experimental but it is used to enable other experimental features. We don't currently have a page that lists the current experimental features and we currently don't expect experimental features to have user-facing documentation.
Regarding CFBundleDisplayName; This key isn't required. DocC doesn't require any Info.plist keys and doesn't require an Info.plist file at all. AFAIK this key is not used to customize the title of the module page. If it has any impact on the module page then that would be a bug. AFAIK the only thing that this key configures is the first path component for articles. This key mostly exist for historical reasons and the general recommendation would be to not use it and instead rely on the default value—which is either the base name of the catalog ('.docc' directory) or the module name of the documented module. Because it's not recommended to specify this key, I don't know if we'd want to have user-facing documentation for it.
Regarding CFBundleIdentifier; Like above, this key isn't required and it only exists for historical reasons. DocC uses this value as one component of each page's "reference" identifier but because DocC treats the entire identifier as an opaque value it practically doesn't make any difference. In theory two different frameworks with the same name that also have symbols with the same name could be distinguished by this component of the value but in practice it's extremely unlikely that any single package would have multiple dependencies with the same name and write a link where a symbol with that name exist in both those dependencies. Like above, the general recommendation would likely be to not specify this key and instead rely on the default value. Because it's not recommended to specify this key, I don't know if we'd want to have user-facing documentation for it.
Thanks for the detailed response, and for the clarification on CFBundleDisplayName. Most of my understanding of the current behavior came from poking around with coding agents, so I appreciate the correction where it missed.
I was originally picturing a dedicated page for people who want to tinker with these keys, but I take your point about surfacing things only where relevant, that probably serves most readers better than a standalone reference.
On CDExperimentalFeatureFlags, is there a specific reason you'd rather not document the features it unlocks? I'm curious if there's a deliberate reason to keep them undocumented versus it just not being a priority.
Also wondering if documenting Info.plist keys at all might be more than most DocC users need. Would it make more sense to put this somewhere like the SwiftDocC reference rather than in the main guides, so it's there for people who go looking but doesn't clutter the primary docs?
It's more the latter (not being a priority). So far we haven't required that new experimental features add documentation which has meant that none of the experimental features have any documentation.
If we were to document that the CDExperimentalFeatureFlags Info.plist key enables experimental features we'd have no documentation to describe how those features work. As such, I'm not sure how much value it would add to document the CDExperimentalFeatureFlags Info.plist key.
One thing I’m still curious about from my last message, what do you think about putting these keys in the SwiftDocC reference (SwiftDocC) instead of the main guides?
It could make some sense to describe what eachdecodedkey is used for.
At the same time, I consider the audience of that library documentation to be API clients and contributors so I don't know if it's the best place for any user-facing documentation. IMO If it's documentation about how to use DocC that we want end-users to know, then the better place for it is in the user-facing documentation. I wouldn't expect end-users to read the library / API documentation, nor do I feel that it should be necessary to read the library / API documentation unless someone is interacting with the library / API directly.
That's a fair distinction, agreed. To start closing this out, what's your final take on moving forward with contextual documentation for CDDefaultCodeListingLanguage and CDDefaultModuleKind? Is it worth adding?