Documentation Tooling Workgroup Meeting - 23 March, 2026

Swift Documentation Tooling
1

Attending

  • Joe Heck
  • Vera Mitchell
  • Sven Schmidt
  • Franklin Schrans
  • Rauhul Varma

Topics

  • (Joe) can provide a short "docs repo" update - there's a few pieces of potentially relevant to the tooling:
    • replicating the concept of a "Disclosure" block - basically matching <summary> and <detail> tags in HTML5
    • multi-platform builds - collecting and merging symbolgraphs from various platforms and annotations
    • Merging separate DocC archives to present a combined archive vs. separate archives
      • public prototype that I'm working on for Swift docs more generally: Documentation

Discussion

Joe: Use of snippets, and potentially wanting to expand that to enable referencing non-swift files, and how to approach that problem space.

  • responsibility falls into the docc plugin to find and transform source files into symbolgraphs that are then handed to DocC (DocC being the passive part of this)
  • orchestration and generation of the symbol graphs being the tricky bit here - where that tooling should/could live, and how to wrangle it with the Swift build systems

Joe: replicating the concept of a "Disclosure" block - basically matching <summary> and <detail> tags in HTML5

  • forum conversations about this a few months ago, with the only meaningful feedback being a request to keep the in-DocC-JSON representation to neutral (equiv of a custom RenderNode) so that it's not bound to only HTML output from the get go. More work, but a very reasonable request given the structures that exist there today.

Joe: Any thoughts or updates on wrangling the mechanics for making multi-platform symbol collections and presenting combined docs for those (macOS, iOS, windows, android, linux)
Vera: precise identifier for the symbols - USR for Swift, Clang
Vera: while back, wrote helper tool to dump unified symbol representation of the directory (dump-unified-graph)
Joe: does symbolgraph know what platform built it?
Vera: yes - there's a meta data that have the components of the triple
Vera: -XswiftC to export flags during regular build

  • swift-symbolgraph-extract - use against framework, needs module name, triple and directory
  • extract-api from headers for Clang to get from a precompiled library, using the symbols from pre-builts

(side conversation that being forced to add docc-plugin as a dependency to get docs building is really troublesome. Some packages refusing, leaving it to CI wrangling or ifdef/ENV based flags to add/remove for Docs building to not impact broader build times. Overlays with the whole orchestration issue with swift build systems, packaging, etc)

Vera: There was a PR introduced to swift Availability - but stalled last year (last summer). There were some explicit complications around implementation, but it was trying to provide a documentation annotation over the actual availability mechanisms. Turns out some of the availability pieces also falls into a mixture with language mode, so annotating when and where that all comes from gets deeply intertwined quite quickly.
Vera: There is a CLI argument to strip out from of availability aliases from the symbolgraphs though - today they are mostly Apple focused, and this tries to prep for making it based on Swift. The flag you can add when building symbols graphs, drop the availability domains from the symbolgraph, so that it's less Apple specific

Franklin: DocC - have we talked about SEO work?
Joe: We're waiting for the full Swift 6.3 release, to overlay with the work that Dave and Sven will need to do already. RCs are out, so we're expecting that pretty shortly.
Joe: Also as a reminder, there's a very reasonable chance, maybe high, that we don't get any decent signal at all from the ad-hoc analysis mechanism (small sample A/B like testing) that we're trying. If we do - that's great. If we don't, it doesn't necessarily mean anything.

Joe: I've been thinking about when to remove the --experimental flags for the code block rendering updates after the 6.3 release - I want to move them to non-experimental in the future, but not sure when
Vera: swift-docc/CONTRIBUTING.md at main · swiftlang/swift-docc · GitHub

Rauhul: code block updates?
Joe: some in flight, the 6.3 updates will be available, but not everything you're asking about has a connection to what's already been done.
Included in 6.3:

  • Copy to clipboard annotation
  • highlighting lines (or strikeout)
  • line numbers on/off
  • (Jesse's contributions are great!)

Joe: The collapsable idea (code folding? or just close the code blocks entirely) are possible with directives, and maybe semi-related to the disclosure summary/detail HTML tags - but those don't yet exist.

  • hyperlink to a filename and reference to GitHub/GitLab location - possible I think, but likely a directive that would need to be added
  • There's some base "hosted library" location flags to provide the base links available in DocC today, and that could build on them.
    Rauhul: code block additions - enabling additional features - linking to source files, applying code folding/collapsable region in the output, even playing through a WASM interpretter if available (mixing ideas from Rust book)

Action Items

  • none