Swift-DocC Documentation

SwiftDocC is a tool for combining code comments with markup prose to produce structured, semantic documentation. It provides APIs to:

• Discover documentation inputs.
• Load catalog content.
• Parse symbol-graph meta-information.
• Extract symbol documentation.
• Pair symbol documentation with external file content.

SwiftDocC represents compiled documentation as an in-memory model, which can then be converted into a persistable representation for writing to disk.

DocC is a documentation compiler that converts Markdown-based text into rich, interactive documentation for Swift frameworks and packages. It supports two primary types of content:

1. API Reference Documentation: Generated by adding documentation markup to your Swift source code. This includes cross-symbol linking, term-definition lists, and code listings.
2. Supplemental Content: Created using documentation markup and specific directives to build interactive tutorials (with coding exercises) or comprehensive articles that explain specific technologies.

You can preview documentation in its published form during development or host the final output on a website.

Swift-DocC allows you to create interactive, step-by-step tutorials for your Swift frameworks and packages. These tutorials augment standard reference documentation by guiding users through coding exercises and realistic project scenarios.

To create a tutorial, you write content in Markdown and use specific DocC directives to define elements such as:

• Introductions
• Sections
• Steps
• Assessments

Once written, you run the DocC compiler to transform your Markdown into a rich, interactive learning format.

Documentation markup is a custom variant of Markdown used by DocC to provide developer-specific features. It extends standard Markdown to support:

• Cross-symbol linking: Easily link to specific APIs or symbols within your project.
• Term-definition lists: Create structured lists of terms and their meanings.
• Code listings: Embed and format code snippets.
• Asides: Add callouts or supplementary notes to your content.

This markup is added directly to your source code or supplemental Markdown files and is processed by the DocC compiler to produce the final documentation site.

A DocumentationContext is the in-memory representation of a documentation unit, such as a module, package, or technology. It serves as the central hub for interacting with the documentation model.

Key responsibilities of a context include:

• Analyzing bundle file contents and converting them into semantic models.
• Managing a graph of DocumentationNode objects (where each node represents a single documentation topic).
• Processing assets like media files or download archives.
• Resolving links to external documentation sources via ExternalDocumentationSource and resolving external symbols via GlobalExternalSymbolResolver.
• Providing random access to documentation data, including graph walking and path finding.

The @Comment directive allows you to include writer notes, reminders, or author comments within your .docc files. These comments are captured during the documentation process but are completely ignored by the DocC renderer. They will not appear in the final, published documentation, making them ideal for internal workflows like marking areas that need more content or adding technical reminders.

@Comment {
    Add lots more photos of sloths here!
}

DocC operates as a compilation pipeline where each stage's input is the previous stage's output. While work is generally performed serially, you can use specific Collection extensions to perform concurrent work when serial processing becomes a bottleneck.

Best Practice: The preferred pattern is to call a function from the main queue, perform concurrent operations inside that function, and return the aggregated results. This keeps concurrency scoped locally within the function and manages complexity.