swiftlang/swift-docc

Swift-DocC is a documentation compiler and toolchain that converts Swift and Objective-C source code and markup into structured documentation archives. It processes symbol graphs and documentation catalogs to generate navigable, searchable sites in multiple formats, including HTML, Markdown, and JSON. The system supports complex features such as multi-language framework handling, external link resolution, and live-reload previewing.

108 changes.

Swift-DocC introduced comprehensive multi-language documentation variants, allowing symbols and content to present different representations based on the target programming language. The project simultaneously unified its error reporting by migrating from the legacy Problem type to a structured Diagnostic model with actionable solutions. These core architectural changes were supported by expanded platform support, including Windows and Android, and the removal of deprecated command-line utilities.

46 changes.

This period focused on expanding the documentation authoring experience by introducing new directives for layout, styling, and code snippets, alongside support for external link resolution and source code navigation. The underlying infrastructure was modernized through a new automatic directive parsing system, simplified input discovery, and robust graph utilities to handle complex symbol relationships and cycles.

23 changes.

This period focused on introducing static HTML documentation rendering and Markdown export capabilities, enabling users to host documentation on static web servers. The command-line interface was significantly modernized through a migration to CMake, an async action architecture, and new subcommands for initialization and merging. These features were supported by comprehensive testing infrastructure, including in-memory utilities and optimized JSON decoding for improved performance.

An experimental command is now available that allows users to write auto-generated curation content directly into documentation extension files. This feature generates markdown representations of automatic curation, including language-specific topic sections, and can append this content to existing extension files or create new ones based on symbol references.

Sources/SwiftDocC/Catalog Processing · high confidence

The DocC command-line interface is now built using CMake (Sources/DocCCommandLine/CMakeLists.txt) instead of the previous build system, and the main entry point (Docc.swift) conditionally registers the 'preview' subcommand when the PREVIEW\_SERVER flag is enabled, allowing users to compile and preview documentation from the command line.

Sources/DocCCommandLine · high confidence

The DocC converter now produces Markdown documentation alongside the existing Render JSON. This is enabled by new \MarkdownOutputManifest\ and \MarkdownOutputNode\ structures that define the output format, and a new \markdownOutput(for:)\ method in \DocumentationContextConverter\ that drives the conversion. Additionally, the converter now accepts a \sourceRepository\ configuration, allowing it to emit URLs linking documentation symbols directly to their source code in a remote repository. The converter's API has been simplified by removing the \DocumentationBundle\ parameter from initialization, relying solely on the \DocumentationContext\ for reference resolution.

Sources/SwiftDocC/Converter · high confidence

This change introduces the core infrastructure for exporting SwiftDocC documentation as Markdown files. It adds the \MarkdownOutputSemanticVisitor\ to traverse the documentation node's semantic structure and the \MarkdownOutputMarkupWalker\ to convert that structure into formatted Markdown text. This includes handling of headings, lists, links, and automatic curation sections, laying the groundwork for generating human-readable Markdown representations of the documentation.

Sources/SwiftDocC/Model/MarkdownOutput · high confidence

A new \ConvertServiceFallbackResolver\ protocol has been added to handle cases where the \ConvertService\ renders a single page that references local symbols, pages, or assets not included in the initial input. This resolver allows the system to on-demand fill in missing local content by resolving references and fetching associated assets, treating the returned content as 'external' since it was not part of the original request scope.

Sources/SwiftDocC/DocumentationService/Convert/Fallback Link Resolution · high confidence

A new DocCCommon library has been added to house shared infrastructure, including a fast custom decoder for symbol graph JSON files to improve processing performance. The library also introduces a fixed-size bit set implementation and refactors source language storage to use this bit-set type, allowing DocC to efficiently manage sets of programming languages within a single execution.

Sources/DocCCommon · high confidence

Adds a new DocCHTML module that renders documentation into static HTML5. This includes an HTML node model, a formatter with options for pretty-printing and compact output, and Markdown renderer extensions that produce HTML for availability, breadcrumbs, declarations (with Swift/Objective-C pretty printing), discussions, parameters, relationships, returns, and topics.

Sources/DocCHTML · high confidence

SwiftDocC now supports generating static HTML documentation output. This change introduces a new HTML rendering pipeline that produces semantic HTML nodes, wraps them into full-page documents with configurable headers and footers, and consumes the resulting content via a dedicated \HTMLContentConsumer\ protocol. The renderer handles link resolution, asset mapping, and metadata extraction to create standalone HTML files suitable for static hosting.

Sources/SwiftDocC/Model/Rendering/HTML · high confidence

Symbol documentation properties (titles, declarations, availability, etc.) are now stored as \DocumentationDataVariants\, allowing a single symbol to present different content for different programming languages (e.g., Swift vs. Objective-C). The \Symbol\ model exposes these as variant collections (e.g., \titleVariants\), and the system now selects the most appropriate language-specific content for display based on the user's context, while maintaining deterministic fallbacks to a default language.

Sources/SwiftDocC/Semantics/Symbol · high confidence

Authors can now use the @Options directive to customize Swift-DocC's default rendering behavior. This new capability allows you to enable or disable the automatic generation of the Overview subheading, the See Also section, and the title heading (eyebrow) on a per-page or global catalog basis. Additionally, you can control the visual presentation of the Topics section by choosing between list, compact grid, detailed grid, or hidden styles.

Sources/SwiftDocC/Semantics/Options · high confidence

The DocC documentation catalog now includes several new articles covering code snippets, images, tables, content formatting, symbol linking, appearance customization, and distribution. These files provide users with detailed guides on using features like the @Snippet directive, table alignment and spanning, theme customization via theme-settings.json, and hosting documentation archives. Additionally, a symbol graph file (docc.symbols.json) and HTML header/footer templates have been added to support the documentation structure and rendering.

Sources/docc/DocCDocumentation.docc · high confidence

A new \SourceRepository\ struct has been added to the \SwiftDocC\ module to handle the generation of URLs for source code files. This type allows documentation to link to declarations in remote repositories (GitHub, GitLab, BitBucket) or local files using a custom \doc-source-file://\ scheme, enabling users to navigate directly to the source code location from the generated documentation.

Sources/SwiftDocC/SourceRepository · high confidence

Authors can now use new directives to structure and style documentation content. The \@TabNavigator\ and \@Tab\ directives allow content to be organized into tabbed sections. The \@Row\ and \@Column\ directives enable grid-based layouts, with \@Column\ supporting \size\ and \alignment\ parameters to control column width and content positioning. The \@Links\ directive provides embedded previews of documentation links in list or grid styles (\compactGrid\, \detailedGrid\, \list\). Additionally, the \@Small\ directive renders its content in a smaller font, suitable for legal or copyright text.

Sources/SwiftDocC/Semantics/Reference · high confidence

A new command-line utility has been added to bin/benchmark to gather, compare, and analyze performance metrics for Swift-DocC. The tool provides several subcommands: 'measure' to collect benchmark data for the current codebase (optionally comparing against a baseline file), 'compare-to' to automatically benchmark both the current checkout and a specified commit before diffing the results, 'measure-commits' to gather metrics across multiple historical commits, 'diff' to perform statistical analysis between two benchmark result files, and 'render-trend' to visualize performance trends. The tool supports configurable repetition counts, custom docc arguments, and outputs results in JSON format for automation, while also providing human-readable terminal tables with color-coded changes and statistical footnotes.

bin/benchmark · high confidence

The DocCTestUtilities library now includes an in-memory file system (TestFileSystem) that allows tests to construct and manipulate documentation catalogs without hitting the disk, supporting both array-based and result-builder syntax for defining folder structures. It also provides helper functions to programmatically generate SymbolGraph objects, including symbols with availability and subheading data, and adds XCTestCase extensions for creating isolated temporary directories to prevent conflicts in CI environments.

Sources/DocCTestUtilities · high confidence

DocC now supports documenting HTTP endpoints, request bodies, parameters, and responses via new \HTTPEndpointSection\, \HTTPBodySection\, \HTTPParametersSection\, and \HTTPResponsesSection\ models. It also adds \DictionaryKeysSection\ for documenting dictionary keys and \PropertyListPossibleValuesSection\ with validation diagnostics for possible values. Additionally, the Topics section now supports anonymous topic groups, allowing content without a level-3 heading to be grouped, and Default Implementations are now sorted by description.

Sources/SwiftDocC/Model/Section · high confidence

A new Swift command-line tool, \update-license-for-modified-files\, has been added to the \bin/update-license-comments\ directory. This utility automatically updates the copyright year in license headers of source files that have been modified. It supports two modes: updating staged files via the \--staged\ flag, or comparing against a specific branch/commit (defaulting to \main\) to find committed changes. The tool identifies files containing the standard Apple/Swift project license comment and updates the year range to include the current year, ensuring license compliance without manual intervention.

bin/update-license-comments · high confidence

The \LinkCompletionTools\ enum is now a public API, providing functions to parse link strings into components, match symbols against those components, and suggest minimal disambiguations for colliding symbols. This enables editor integrations to implement intelligent link completion by leveraging symbol kind, hash, and type signature information (including parameter and return types) to resolve ambiguous references.

Sources/SwiftDocC/DocumentationService/Convert/Symbol Link Resolution · high confidence

The rendering engine now supports computing differences between two RenderNode documents. This change introduces a new diffing subsystem in the \Diffing\ module, including \AnyRenderReference\ and \AnyRenderSection\ to handle type-erased comparison of references and sections, a \DifferenceBuilder\ to aggregate JSON Patch operations, and extensions to \RenderNode\ that implement the \RenderJSONDiffable\ protocol. Users can now generate JSON Patch differences to identify changes in documentation content, such as updates to abstracts, sections, references, and metadata.

Sources/SwiftDocC/Model/Rendering/Diffing · high confidence

SwiftDocC now allows documenting HTTP request and response semantics, including request bodies, parameters, and response codes, via new semantic models (HTTPBody, HTTPParameter, HTTPResponse). It also adds experimental support for parsing Doxygen-style \\param and \\returns commands, enabling documentation of parameters and return values from Doxygen comments. Additionally, parameter and return value documentation now tracks source ranges and standalone status, and uses existential any for markup collections.

Sources/SwiftDocC/Model/Semantics · high confidence

Users can now embed code examples from the project's 'Snippets' directory using the new @Snippet directive. The directive accepts a path to a snippet file and an optional 'slice' argument to display only a specific portion of the code, defined by // snippet.\<name\> and // snippet.end annotations within the source file. By default, the full snippet and its accompanying explanation are rendered; specifying a slice limits the output to the requested line range.

Sources/SwiftDocC/Semantics/Snippets · high confidence

The rendering model now supports multi-language documentation by introducing variant collections for key properties in \RenderNode\ (such as abstracts, primary content, and topic sections) and adding a \variantOverrides\ property to store language-specific JSON patches. The \DocumentationContentRenderer\ and \LinkTitleResolver\ have been updated to produce \VariantCollection\ outputs for symbol titles and subheadings, allowing the system to render different content based on the target programming language. Additionally, the \RenderNode\ version was bumped to 1.3 to reflect these structural changes.

Sources/SwiftDocC/Model/Rendering · high confidence

DocC can now resolve documentation links to content in other pre-built DocC archives. This change introduces an external link resolution system that loads dependency archives, parses their link hierarchies, and indexes their symbols for navigation. Users will see improved link resolution for cross-archive references, with external content appearing in the navigator and proper error diagnostics when links cannot be resolved.

Sources/SwiftDocC/Infrastructure/Link Resolution · high confidence

The DocC command-line tool now includes a StaticHostableTransformer that generates static website files from documentation archives. This allows users to host their generated documentation on static web servers. The transformer creates an index.html file for each JSON data file in the archive and supports a custom hosting base path, which is injected into the HTML template to ensure correct relative linking when the documentation is served from a subdirectory.

Sources/DocCCommandLine/Transformers · high confidence

The documentation rendering system now supports applying variant overrides (such as language-specific content) to render nodes via JSON Patch operations. This change introduces a new infrastructure in the Variants module, including \JSONPatchApplier\ and \JSONPointer\ types to handle RFC 6902 patches, and \RenderNodeVariantOverridesApplier\ to apply these patches to encoded render nodes. Variant collections now encode their trait-specific overrides as patches rather than embedding full alternative values, allowing clients to selectively apply overrides based on their context (e.g., selecting the Objective-C variant for an Objective-C documentation page) while keeping the base JSON payload smaller.

Sources/SwiftDocC/Model/Rendering/Variants · high confidence

Swift-DocC now supports building with CMake in addition to Swift Package Manager, enabling builds on Linux, FreeBSD, and OpenBSD. The toolchain now requires Swift 5.9, and the Dockerfile has been updated to run tests without root permissions. Several new features are available, including code block annotations (copy-to-clipboard, highlight, strikeout, wrap, showLineNumbers), precise diagnostic severity control, and the ability to write diagnostics to a file. The project also removes the dependency on Swift-NIO SSL and updates contributor documentation to reflect the move to GitHub issues.

(repo-wide) · high confidence

This change adds several new directives to the \@Metadata\ block, allowing authors to customize how documentation pages are presented and linked. You can now define alternate language representations for symbols using \@AlternateRepresentation\, specify platform availability and deprecation versions with \@Available\, and add prominent action buttons with \@CallToAction\. Page appearance is enhanced with \@PageImage\ for icons and cards, \@PageColor\ for accent colors, and \@PageKind\ to set the page type (article or sample code). Additionally, \@DisplayName\ allows overriding symbol names, \@TitleHeading\ customizes page headings, \@SupportedLanguage\ controls article language availability, and \@CustomMetadata\ lets you inject arbitrary key-value pairs into the page metadata. The \DocumentationExtension\ directive has also been updated to warn when its default \append\ behavior is explicitly specified without effect.

Sources/SwiftDocC/Semantics/Metadata · high confidence

The \Sources/DocCDocumentation\ directory has been cleared of its documentation catalog contents. This includes the deletion of the \DocC.symbols.json\ symbol graph, all Markdown reference syntax pages (such as \Metadata\, \TechnologyRoot\, and \Image\), tutorial content, developer distribution guides, and the custom \header.html\ and \footer.html\ templates. The documentation source files that previously defined the structure, styling, and reference material for the DocC tool are no longer present in this location.

Sources/DocCDocumentation · high confidence

The \SwiftDocCUtilities\ library, which previously provided the \Action\ protocol and concrete implementations for command-line documentation tasks (such as \ConvertAction\ and \IndexAction\), has been removed. This eliminates the public API surface for programmatic documentation conversion and indexing via this specific utility module, requiring users to rely on the main \SwiftDocC\ library or direct tool invocation for these capabilities.

Sources/SwiftDocCUtilities/Action · high confidence

The \Convert\, \Index\, and \Preview\ command-line subcommands have been removed from the \docc\ utility. This deletion eliminates previously deprecated APIs and command-line interfaces, meaning users can no longer invoke these specific commands directly via the CLI.

Sources/SwiftDocCUtilities/ArgumentParsing/Subcommands · high confidence

The \DocumentationCoverageOptionsArgument\ and \PreviewExternalConnectionOptions\ argument structures have been removed from the CLI. This eliminates the \--experimental-documentation-coverage\ flag and the ability to configure preview server external connections via environment variables (\DOCC\_PREVIEW\_USERNAME\, \DOCC\_PREVIEW\_PASSWORD\, \DOCC\_TLS\_CERTIFICATE\_CHAIN\, \DOCC\_TLS\_CERTIFICATE\_KEY\). Users relying on these specific command-line arguments or environment-based configurations for documentation coverage levels or secure preview connections will need to adopt the current supported alternatives.

Sources/SwiftDocCUtilities/ArgumentParsing/Options · high confidence

The \Sources/SwiftDocCUtilities/Docc.swift\ file, which defined the \Docc\ struct as the primary command-line interface for the documentation compiler, has been deleted. This change removes the root command configuration that previously exposed the \convert\, \index\, and \preview\ subcommands through this specific entry point, effectively stripping the main CLI wrapper from this source location.

Sources/SwiftDocCUtilities · high confidence

New internal graph utilities have been added to the \DirectedGraph\ type to support robust topic graph construction. These additions include cycle detection methods (\firstCycle\, \cycles\) to identify and handle cyclic curation references, as well as path traversal helpers (\allFinitePaths\, \shortestFinitePaths\, \reachableLeafNodes\) and standard BFS/DFS iterators. These changes prevent infinite recursion during documentation processing when content contains cyclic references.

Sources/SwiftDocC/Utility/Graphs · high confidence

The communication bridge now uses the explicit \any\ keyword for existential types (e.g., \any Error\, \any Decoder\) to align with Swift's modern concurrency and type-safety standards. Additionally, the \MessageType\ struct now conforms to \Sendable\ to support concurrent access, and the \WebKitCommunicationBridge\ has been refactored to remove unnecessary backtick escaping in JavaScript injection, simplifying the message passing logic.

Sources/SwiftDocC/Infrastructure/Communication · high confidence

The internal communication foundation now uses the explicit \any\ keyword for existential types (e.g., \any Encodable\, \any Decoder\), aligning with Swift's modern syntax requirements. Additionally, JSON encoding is now consistently configured to sort keys and pretty-print output regardless of the platform version, ensuring deterministic and stable serialization results across all supported environments.

Sources/SwiftDocC/Infrastructure/Communication/Foundation · high confidence

The documentation service models now leverage Swift's upcoming language features to improve safety and module boundaries. The \DocumentationServer.services\ dictionary has been updated to use opaque types (\any DocumentationService\) instead of generic type parameters, and the \MessageType\ struct now conforms to \Sendable\ to support strict concurrency checking. Additionally, imports for the \Foundation\ framework have been changed to \public import\, exposing the framework's types to consumers of this module.

Sources/SwiftDocC/DocumentationService/Models · high confidence

The code color infrastructure now uses the explicit \any\ keyword for existential types in \Codable\ conformance methods, aligning with Swift's SE-0335 standard. Additionally, the \SRGBColor\ type no longer provides initializers for \UIColor\ or \NSColor\, removing dependencies on UIKit and AppKit to make the component more platform-agnostic.

Sources/SwiftDocC/Infrastructure/Communication/Code colors · high confidence

The rewriter module now requires the SE-0335 (Existential any) upcoming feature, updating protocol conformances in \RenderNodeTransforming\ and \RenderNodeTransformationComposition\ to use the \any\ keyword. This change also removes the deprecated \RenderNodeTransformation\ typealias and deletes the \RemoveAutomaticallyCuratedSeeAlsoSectionsTransformation\ component, while updating \RemoveHierarchyTransformation\ to handle hierarchy variants and \RenderNodeTransformer\ to use \public import Foundation\.

Sources/SwiftDocC/Converter/Rewriter · high confidence

Documentation articles now record which symbols they reference, enabling a "Mentioned In" section in symbol documentation that lists articles sorted by mention frequency and alphabetically for ties. The article parser now supports the \@Options\ directive for configuring article options and the \@SupportedLanguage\ directive within \@Metadata\ to specify supported languages. Additionally, the \MarkupConvertible\ and \DirectiveConvertible\ protocols have deprecated the \context\ parameter in their initializers, and the \Problem\ type has been replaced by \Diagnostic\ for reporting issues during article parsing.

Sources/SwiftDocC/Semantics/Article · high confidence

DocC now automatically capitalizes the first word of paragraphs, asides, headings, and small text blocks during rendering. This change ensures consistent typographic presentation by applying title-case logic to the initial word of these block elements, while leaving other content types unchanged.

Sources/SwiftDocC/Model/Rendering/Content · high confidence

The benchmarking subsystem now uses a new \BenchmarkResults\ structure for output, replacing the previous ad-hoc encoding with a structured model that supports duration, memory, disk, and checksum metrics. This change also expands platform detection to include Android, FreeBSD, and OpenBSD, and refactors the public \benchmark\ API to use existential types for metrics while maintaining backward compatibility with legacy JSON formats during decoding.

Sources/SwiftDocC/Benchmark · high confidence

The \Checker\ protocol and its conforming types (\AnyChecker\, \CompositeChecker\) now expose a \diagnostics\ property of type \\[Diagnostic\]\ instead of the legacy \problems\ property, with the old API deprecated to ensure a smooth transition. This change standardizes how markup validation issues are reported. Additionally, a new validation rule has been introduced: the checker now emits a warning if a 'Topics' section (identified as a level-2 heading titled 'Topics') lacks at least one subheading, helping authors maintain proper documentation structure.

Sources/SwiftDocC/Checker · high confidence

The ConvertRequest model has been significantly restructured to support new capabilities and improve clarity. Bundle metadata is now encapsulated in a new bundleInfo property, replacing the previous displayName, identifier, and version fields. New properties allow clients to override documentation comments for specific symbols, control whether source file URIs are emitted in the output, and include tutorial files alongside standard markup. Additionally, the request now supports specifying expanded documentation requirements for symbols, enabling conditional availability of detailed documentation based on access levels.

Sources/SwiftDocC/DocumentationService/Models/Services · high confidence

The ConvertService's processing method is now asynchronous, moving from a synchronous Result-based pipeline to an async/await model that improves responsiveness. Internally, the previous OutputConsumer and InMemoryContentDataProvider have been removed and replaced with a streamlined InMemoryDataProvider and a new makeBundleAndInMemoryDataProvider helper, which simplifies how in-memory documentation assets (symbol graphs, markup, tutorials) are registered and consumed during conversion.

Sources/SwiftDocC/DocumentationService/Convert · high confidence

Asset registration is now deterministic: when multiple variants exist for the same asset name, the system selects the best match based on trait overlap, preferring user interface style over display scale, and uses the lexicographically smallest URL path to break ties. Additionally, SVG assets now automatically extract and store their first \id\ attribute in variant metadata via the new \SVGIDExtractor\, making this identifier available for documentation references.

Sources/SwiftDocC/Infrastructure/Bundle Assets · high confidence

The generate-symbol-graph tool now records the earliest Swift-DocC version that supports each directive and identifies the specific implementation type for undocumented directives, enabling better tracking of directive availability. Additionally, the tool silences compiler warnings about retroactively conforming types from other modules to new protocols by using fully-qualified type names for these extensions.

Sources/generate-symbol-graph · high confidence

The documentation authoring experience is improved by replacing the legacy \Problem\-based diagnostic system with a modern \Diagnostic\ type that supports structured solutions and better error reporting. Directive parsing is now driven by the new \AutomaticDirectiveConvertible\ protocol, which uses property wrappers (like \@DirectiveArgumentWrapped\ and \@ChildDirective\) to automatically handle validation and initialization, significantly reducing boilerplate. This change also introduces a centralized \DirectiveParser\ utility, renames the \Technology\ semantic model to \TutorialTableOfContents\ for clarity, and migrates link resolution to provide more specific error messages and fix-it suggestions for unresolved references.

Sources/SwiftDocC/Semantics · high confidence

The DocC command-line interface has been reorganized to improve usability and clarity. The \index\ command is now deprecated in favor of the \--emit-lmdb-index\ flag on the \convert\ command, which will be removed after the Swift 6.6 release. A new \init\ subcommand allows users to generate documentation catalogs from templates (e.g., \articleOnly\, \tutorial\). The \merge\ subcommand enables combining multiple documentation archives into a single output. Documentation coverage options have been refined with new flags like \--coverage-summary-level\ and \--coverage-symbol-kind-filter\. Source repository information can now be specified via \--source-service\, \--source-service-base-url\, and \--checkout-path\ to support external link generation. Additionally, the \transform-for-static-hosting\ subcommand and related flags have been promoted to non-experimental status and enabled by default, while the internal \DocumentationBundleOption\ has been renamed to \DirectoryPathOption\ for clarity.

Sources/DocCCommandLine/ArgumentParsing/Subcommands · high confidence

The DocC command-line interface has been updated to run asynchronously using Swift's Task API, allowing for better cancellation handling during preview operations. Additionally, the supported operating systems have been expanded to include Android, Windows, FreeBSD, and OpenBSD, removing the previous restriction that limited the CLI to macOS and Linux.

Sources/docc · high confidence

The DocC command-line interface has been refactored to support asynchronous execution, with the \Action\ extension renamed to \AsyncAction\ and its \performAndHandleResult\ method updated to an async function. This change is accompanied by a significant restructuring of the \ConvertAction\ initialization to centralize feature flags, diagnostic severity controls, and catalog discovery options, replacing the previous scattered parameter approach. Additionally, internal targets and file paths have been renamed from \SwiftDocCUtilities\ to \DocCCommandLine\ to better reflect the module's purpose, and minor syntax updates were applied to argument validators.

Sources/DocCCommandLine/ArgumentParsing/ActionExtensions · high confidence

The DocC command-line interface has been restructured to use a new \AsyncAction\ protocol, replacing the previous synchronous workflow with an asynchronous model. This change introduces dedicated action types for core tasks—such as \ConvertAction\ for documentation conversion, \InitAction\ for creating new catalogs from templates, and \IndexAction\ for building navigation indexes—allowing for better concurrency and more modular command execution. The refactoring also includes new file-writing consumers (\FileWritingHTMLContentConsumer\, \FullPageHTMLContentConsumer\) that handle HTML generation and static hosting transformations, and utility extensions for safe file and directory operations, fundamentally changing how the CLI manages and executes documentation tasks.

Sources/DocCCommandLine/Action · high confidence

The documentation checker system has been updated to use the \Diagnostic\ type directly instead of the deprecated \Problem\ wrapper, simplifying how warnings and errors are reported. Several new or refined checks are now active: \InvalidCodeBlockOption\ validates code block options like \highlight\ and \strikeout\ indices; \MiscasedSectionHeading\ warns when standard section headings (e.g., 'See Also', 'Topics') are not capitalized correctly; \SeeAlsoInTopicsHeadingChecker\ flags 'See Also' headings at the wrong level; \InvalidAdditionalTitle\ distinguishes between multiple page titles and multiple symbol extensions in documentation files; and \NonInclusiveLanguageChecker\ now provides specific replacement suggestions and handles multi-space word detection. Existing checkers like \DuplicateTopicsSections\ and \NonOverviewHeadingChecker\ also provide improved solutions and notes.

Sources/SwiftDocC/Checker/Checkers · high confidence

The DocC documentation site now loads its header and footer styles and scripts from external Swift.org assets (JS/CSS) instead of embedding them directly, and updates the copyright year to 2021-2024. The main documentation page (SwiftDocC.md) has been refreshed to reflect current input discovery behavior, renaming the \.docc\ folder to a "documentation catalog," clarifying file extensions (e.g., \.md\, \.tutorial\, \.symbols.json\), adding support for \theme-settings.json\, and introducing new documentation sections for link resolution, feature flags, and adding diagnostics.

Sources/SwiftDocC/SwiftDocC.docc · high confidence

This change introduces several updates to the documentation model. A new \Availability\ type is added to consolidate availability information from multiple sources, while \ParametersAndReturnValidator\ is introduced to validate and filter parameter and return value documentation based on function signatures. The \AttributedCodeListing\ and \SourceLanguage\ types are removed, and \BuildMetadata\ is updated to use a new \bundleID\ property. Additionally, \DocumentationNode\ gains support for virtual nodes, authored options, and metadata, and \DocumentationMarkup\ is refactored to better handle deprecation summaries and abstract parsing.

Sources/SwiftDocC/Model · high confidence

The DocCCommandLine documentation has been updated to reflect the new \InitAction\ command, which allows users to generate documentation catalogs from \articleOnly\ or \tutorial\ templates. The documentation also clarifies the command-line workflow, noting the use of \AsyncParsableCommand\ for custom tools and listing available actions like \ConvertAction\, \PreviewAction\, and \IndexAction\. Additionally, the documentation structure has been reorganized, with some files renamed and moved to better align with the \DocCCommandLine\ module name, and some command-line options have been updated or removed.

Sources/DocCCommandLine/CommandLine.docc · medium confidence

The \DownloadReference\ and \XcodeRequirementReference\ types now conform to \RenderJSONDiffable\, enabling the system to compute differences between reference states for features like diffing render nodes. \DownloadReference\ has been updated to support verbatim URL encoding (preserving original URLs during round-trips) and its checksum property is now optional, allowing explicit null values to be encoded. Both types also adopt \Equatable\ for easier comparison.

Sources/SwiftDocC/Model/Rendering/Tutorial/References · high confidence

This update improves the documentation rendering model by introducing \RenderJSONDiffable\ conformance to most symbol render sections (such as \AttributesRenderSection\, \DeclarationsRenderSection\, and \ParametersRenderSection\), enabling the generation of JSON patches for efficient documentation updates. Availability information is refined: the \AvailabilityRenderItem\ now uses non-optional booleans for \isUnconditionallyDeprecated\ and \beta\ (defaulting to false), while deprecated fields like \obsoleted\ and \message\ are marked for removal. New capabilities include \MentionsRenderSection\ for tracking symbol mentions, \PropertyListDetailsRenderSection\ for property list key details, and \sameShape\ constraint support in \ConformanceSection\. Additionally, declaration tokens can now be highlighted as changed to show differences in overloaded symbols, and REST/Property List sections are made public.

Sources/SwiftDocC/Model/Rendering/Symbol · high confidence

The documentation processor now recognizes a significantly larger set of block directives, including new additions like @AlternateRepresentation, @SupportedLanguage, and @Assessments, while explicitly listing directives that are removed from content after parsing (such as @Comment and @Redirect). Internally, the system introduces new utility extensions for handling source ranges and detecting links in headings, and updates the visibility of the Markdown import to public to support these protocol definitions.

Sources/SwiftDocC/Utility/MarkupExtensions · high confidence

The external documentation integration system has been updated to use a new V2 communication protocol between DocC and external link resolver executables, replacing the deprecated V1 protocol. This new protocol introduces a capabilities-based handshake, allowing resolvers to declare support for optional features, and provides richer response types for both successful resolutions and failures. Additionally, the integration now relies on the new \ExternalDocumentationSource\ and \GlobalExternalSymbolResolver\ protocols, which replace the older \ExternalReferenceResolver\ and \ExternalSymbolResolver\ protocols. The V1 protocol types and the old resolver protocols have been deprecated and are no longer recommended for new implementations.

Sources/SwiftDocC/Infrastructure/External Data · high confidence

The external link walker has been refactored to track external references by their source documentation input identifier rather than treating all links as belonging to a single bundle. This change updates the \ExternalMarkupReferenceWalker\ and \ExternalReferenceWalker\ to accept a local input identifier and return collected links grouped by source, enabling more precise resolution of external links across multiple documentation inputs. Additionally, the walker now explicitly handles tutorial table of contents structures and fixes a typo in the assessment handling logic.

Sources/SwiftDocC/Semantics/ExternalLinks · high confidence

DocC now uses a custom, high-performance JSON decoder for symbol graph files. This new implementation performs a single linear scan of the JSON data bytes, avoiding the overhead of standard decoding libraries, which significantly reduces the time and memory required to parse symbol graph data.

Sources/DocCCommon/JSONDecoding · high confidence

The FoundationExtensions module has been significantly reorganized and expanded with new utility functions and platform support. New extensions include \capitalizingFirstWord()\ for string auto-capitalization, \isAbsoluteWebURL\ for URL validation, and \baseType()\ for retrieving the underlying type of Arrays and Optionals. The \Dictionary\ extension now supports decoding \Decodable\ types from \Any\ values, and \String\ gains path manipulation helpers like \appendingTrailingSlash\. Platform compatibility is improved with \AutoreleasepoolShim\ now supporting Android, Windows, FreeBSD, and OpenBSD, and a new \NoOpSignposterShim\ allows signpost usage without the \os\ module. Several legacy files were removed or renamed, and strict concurrency warnings are addressed via a \SendableMetatype\ shim for Swift 6.2.

Sources/SwiftDocC/Utility/FoundationExtensions · high confidence

The @Image and @Video directives in DocC documentation now accept a \caption\ argument to display text alongside the media, and a \deviceFrame\ argument to wrap the media in a device frame (controlled by the \isExperimentalDeviceFrameSupportEnabled\ feature flag). The underlying semantic models have been refactored to use the new \AutomaticDirectiveConvertible\ protocol, replacing the previous manual parsing logic with declarative \@DirectiveArgumentWrapped\ properties, and the base \Media\ class has been converted to a protocol.

Sources/SwiftDocC/Semantics/Media · high confidence

The documentation server now correctly handles file paths and MIME types on Windows. Path separators are normalized to backslashes on Windows to ensure files are found, and MIME type detection uses platform-specific APIs (FindMimeFromData on Windows, UTType on macOS) for more accurate content type identification. Additionally, SVG and GIF image types are now explicitly supported with correct MIME types. The server's file providers now accept a FileManagerProtocol abstraction, allowing for better testability and dependency injection.

Sources/SwiftDocC/Servers · high confidence

The LineHighlighter now supports resolving external content with topic images, allowing it to read file content from resolved assets when local resources are unavailable. Additionally, the internal implementation has been refactored to remove an unnecessary intermediate struct and simplify the iterative highlighting logic, while the Highlight struct now conforms to Equatable for easier comparison.

Sources/SwiftDocC/Model/Rendering/Tutorial · high confidence

DocC now transforms extension symbol graphs into a unified 'Extended Type' format, aggregating multiple extension declarations for the same type into single symbols with combined access control and documentation. This change also updates automatic curation to generate language-specific topic sections, ensuring that inherited symbols and default implementations are curated correctly per language variant rather than as a single shared collection.

Sources/SwiftDocC/Infrastructure/Symbol Graph · high confidence

The documentation service now uses structured logging via the \os\ framework (with a no-op shim for environments lacking it) instead of the previous generic error logging, providing clearer, categorized messages for external reference resolution failures. Additionally, the default server configuration now explicitly disallows arbitrary catalog directories during conversion, enforcing stricter validation for incoming documentation sources.

Sources/SwiftDocC/DocumentationService · high confidence

The indexing system in SwiftDocC now includes platform availability information in search results, allowing users to see which platforms a documentation element supports. Additionally, documentation nodes with empty titles are now skipped during indexing rather than causing errors, improving the robustness of the search index for malformed or incomplete symbol graphs.

Sources/SwiftDocC/Indexing · high confidence

The documentation rendering index now uses schema version 0.1.2, introducing new metadata fields for documentation nodes. Renderers can now detect if a node is marked as beta (isBeta), belongs to an external archive (isExternal), or has a custom icon (icon), allowing for appropriate visual treatment in the UI. The index also explicitly tracks deprecated status and supports merging multiple documentation archives, handling image reference collisions during the merge process.

Sources/SwiftDocC/Indexing/RenderIndexJSON · high confidence

The LMDB utility library updates its API to use Swift 5.9's \some\ opaque return types, replacing explicit generic type parameters in \get\, \put\, and \delete\ methods for a cleaner interface. It also introduces platform-specific handling for Windows by defining a \ModeType\ typealias and adjusting file mode defaults, while removing legacy Swift 4.2/5.0 conditional compilation blocks and restricting certain array data conversions to Apple platforms.

Sources/SwiftDocC/Utility/LMDB · high confidence

Automatic curation now respects source language variants, ensuring that 'See Also' sections and topic groups only include symbols available in the current language representation. The system also limits the number of items in automatic 'See Also' sections (defaulting to 15, configurable via the DOCC\_AUTOMATIC\_SEE\_ALSO\_LIMIT environment variable) and prevents extension pages from generating their own documentation pages when their children are curated elsewhere. Under the hood, the Topic Graph has been refactored to use a separate DirectedGraph for traversal, and new node properties (isVirtual, isEmptyExtension, shouldAutoCurateInCanonicalLocation) allow for more precise control over which symbols appear in the documentation hierarchy.

Sources/SwiftDocC/Infrastructure/Topic Graph · high confidence

The LinkDestinationSummary model has been updated to support multi-language content via a new Variant structure, allowing properties like title, abstract, and declaration fragments to vary by source language. Additionally, a new FastJSONDecodable implementation has been added to significantly speed up the decoding of link destination summaries, and the model now includes fields for absolute presentation URLs, topic images, and specific declaration fragments (subheading and navigator) to improve link rendering context.

Sources/SwiftDocC/LinkTargets · high confidence

The navigation tree rendering models (RenderHierarchy, RenderReferenceHierarchy, and related structs) now conform to Equatable and the internal RenderJSONDiffable protocol, enabling the system to compute differences between hierarchy states for efficient updates. Additionally, the RenderHierarchyTranslator has been updated to generate breadcrumb paths using language-specific variants for symbols, ensuring that multi-language symbols display the correct navigation context for the user's selected interface language rather than a single canonical path.

Sources/SwiftDocC/Model/Rendering/Navigation Tree · high confidence

The navigator index now carries richer metadata for each item, allowing users to see beta status, deprecation state, and custom icons in the navigation tree. \NavigatorItem\ has new \isBeta\, \isDeprecated\, and \icon\ properties, and the index builder populates them from render node data (e.g., platform beta flags, unconditional deprecation, and icon images). The serialization format was extended to persist these fields while remaining backward compatible with older indexes. Additionally, the index reader now supports an \onNodeRead\ callback to attach data to nodes during load, and the deprecated \identifierToNode\/\nodeToIdentifier\ maps in \NavigatorTree\ were removed.

Sources/SwiftDocC/Indexing/Navigator · high confidence

Swift-DocC introduces a new internal directive parsing infrastructure in the \DirectiveInfrastructure\ module that uses property wrappers (\@DirectiveArgumentWrapped\, \@ChildDirective\, \@ChildMarkup\) to automatically parse directive arguments, child directives, and markup content. This change centralizes directive parsing and declaration logic, allowing directives to be defined by conforming to the \AutomaticDirectiveConvertible\ protocol and reflecting their structure via \DirectiveMirror\. The \DirectiveIndex\ now pre-populates a registry of top-level directives (including \@Row\, \@Column\, \@Options\, \@Small\, \@TabNavigator\, \@Links\, \@Image\, and \@Video\) and their children, enabling automatic validation and conversion from block directive markup to semantic objects.

Sources/SwiftDocC/Semantics/DirectiveInfrastructure · high confidence

The documentation rendering pipeline now uses a set of dedicated, single-responsibility translators to convert symbol data into render node sections. This change introduces new translator components for Attributes, Declarations, Dictionary Keys, Discussion, HTTP Body, HTTP Endpoints, HTTP Parameters, HTTP Responses, Mentions, Parameters, Property List Details, Possible Values, and Returns. Each translator handles the specific logic for its section (such as highlighting declaration differences, parsing REST endpoint URLs, or formatting HTTP response codes), replacing the previous monolithic approach and making the rendering logic more maintainable and explicit.

Sources/SwiftDocC/Model/Rendering/RenderSectionTranslator · high confidence

The rendering logic for term lists and string manipulation has been updated to improve performance and align with modern Swift standards. The \removingLeadingWhitespace\ and \removingTrailingWhitespace\ methods on \String\ now use index-based slicing instead of iterative character dropping, avoiding unnecessary string copies when no whitespace is present. Additionally, the codebase adopts the SE-0335 \any\ keyword for existential types (e.g., \any RenderContent\, \any ListableItem\) and updates collection extension syntax to the generic parameter form (\Collection\<RenderBlockContent.ListItem\>\). The \Markdown\ import is also scoped as private to reduce namespace pollution.

Sources/SwiftDocC/Model/Rendering/Content/Extensions · high confidence

The PreviewServer now injects a live-reload script into served pages and exposes an SSE endpoint at /\_\docc-live-reload\\_ to notify clients of changes, automatically refreshing the browser when documentation updates. This feature is available on non-Linux/Android/Windows/FreeBSD/OpenBSD platforms. Additionally, the server no longer supports SSL/TLS or HTTP Basic Authentication; the init parameters for username, password, and certificate URLs have been removed, and the server now binds only to plain HTTP. The server's internal state management has also been refactored to use a synchronized state struct to address race conditions during start and stop operations.

Sources/DocCCommandLine/PreviewServer · high confidence

The utility data structures module has been updated to modernize its implementation and simplify its API. The \BidirectionalMap\ type now conforms to \Sequence\, allowing it to be iterated directly, and its internal syntax has been updated to use Swift 5.9's pattern-matching features. Additionally, the \BidirectionalTree\ and \File\ hierarchy (including \Folder\, \InfoPlist\, and \TextFile\ types) have been removed from this location, while a new \GroupedSequence\ type has been added to provide efficient, key-based grouping of elements.

Sources/SwiftDocC/Utility/DataStructures · high confidence

The benchmarking system in Swift DocC now provides more precise and platform-agnostic measurements. Duration metrics now report values in seconds rather than milliseconds, and external link resolution metrics distinguish between successful and failed resolutions, ignoring failures in checksums. Output size benchmarking has been split into specific metrics for the total archive, data subdirectory, and index subdirectory. Peak memory usage now supports Windows, Android, FreeBSD, and OpenBSD in addition to macOS, iOS, and Linux, and reports values in bytes. Additionally, various hash metrics now use a dedicated checksum type instead of generic strings.

Sources/SwiftDocC/Benchmark/Metrics · high confidence

The \PreviewAction\ command initialization no longer accepts or processes TLS certificate keys, chains, or server credentials (username/password) from preview options, and the \CredentialArgumentValidator\ utility for enforcing username and password complexity rules has been removed. Users can no longer configure secure external connections or provide authentication credentials when running the preview command via these specific argument paths.

Sources/SwiftDocCUtilities/ArgumentParsing/ActionExtensions · high confidence

The custom \header.html\ and \footer.html\ files, which previously provided embedded HTML and CSS for the documentation site's header and footer, have been removed from the \SwiftDocCUtilities\ source bundle. This change eliminates the local styling and layout definitions for these UI components, aligning with the project's shift to using external assets for these elements.

Sources/SwiftDocCUtilities/SwiftDocCUtilities.docc · high confidence

The semantic walker now recognizes and visits 'Tutorial Table of Contents' nodes instead of 'Technology' nodes. This change updates the internal visitor methods (visitTutorialTableOfContents) and associated debugging output to reflect the new terminology, aligning the documentation processing logic with the current content model for tutorials.

Sources/SwiftDocC/Semantics/Walker · high confidence

The \DocumentationBundle\ type has been removed and replaced by \DocumentationContext.Inputs\. This new type consolidates build inputs (symbol graphs, markup, resources, and metadata) directly into the documentation context, simplifying the initialization flow and removing the previous two-step creation process. The old \DocumentationBundle\ type is deprecated and will be removed after version 6.5.

Sources/SwiftDocC/Infrastructure · high confidence

The workspace infrastructure has been refactored to replace the legacy 'bundle' terminology with 'catalog' and to introduce robust fallback mechanisms for missing metadata. The old \DocumentationWorkspace\, \DocumentationWorkspaceDataProvider\, and \FileSystemProvider\ types have been removed and replaced with a new \CatalogDiscoveryOptions\ struct, which allows users to provide fallback values for missing \Info.plist\ fields (such as display name and bundle identifier) and specify additional symbol graph files. The \DocumentationContext.Inputs.Info\ model now handles decoding from \Info.plist\ with these fallbacks, and \DefaultAvailability\ has been updated to support an 'unavailable' platform status. This change simplifies workspace configuration by allowing metadata to be supplied externally rather than requiring a complete \Info.plist\ in every discovered catalog.

Sources/SwiftDocC/Infrastructure/Workspace · high confidence

The documentation input discovery mechanism has been replaced with a simplified implementation. This introduces a new \DataProvider\ protocol and an \InMemoryDataProvider\ to abstract file content retrieval, allowing for mixed in-memory and on-disk data sources. The \InputsProvider\ now handles catalog discovery and input categorization (markup, symbol graphs, resources, etc.) directly within the \DocumentationContext\ extension, streamlining how documentation catalogs are found and processed.

Sources/SwiftDocC/Infrastructure/Input Discovery · high confidence

The \bin/make-test-bundle\ tool now uses the \swift package dump-symbol-graph\ command instead of the deprecated \swift symbolgraph-extract\ tool. This change removes the need to manually build the package, query target information via \swiftc -print-target-info\, and locate the SDK path, simplifying the generation process. Additionally, static properties in generated test code are now correctly emitted as \let\ instead of \var\, and a now-unused \SwiftTarget\ struct has been removed.

bin/make-test-bundle · high confidence

Authors can now associate custom images and colors with documentation topics using the new TopicImage and TopicColor reference types, which are exposed in TopicRenderReference via a new images property and a renamed property list key structure. TopicRenderReference also supports variant overrides for titles, abstracts, and fragments, allowing different content per language or platform. Additionally, asset references now include external locations, and all reference types implement RenderJSONDiffable to support deterministic output and diffing of rendered documentation.

Sources/SwiftDocC/Model/Rendering/References · high confidence

The documentation coverage feature now includes options to track and report coverage for dictionary types and HTTP/REST requests. Users can filter coverage statistics to include these new kinds using the 'dictionary' and 'http-request' flags. Additionally, coverage analysis now treats extensions to external types (such as extended classes, structures, and protocols) as part of the respective base type's coverage, aligning with Swift's handling of external extensions.

Sources/SwiftDocC/Coverage · high confidence

The render node model now supports variant overrides, allowing documentation to specify different content for different language or platform variants. This change introduces a \variantOverrides\ field in the render node JSON and updates the decoder to handle it. Additionally, metadata fields such as modules, platforms, titles, and access levels are now stored as variant collections, enabling per-variant values. New metadata directives like \@PageImage\, \@PageColor\, and \@Options\ are supported, and the decoder is made more robust by handling missing references keys. The \CodableContentSection\ now supports a \mentions\ section, and \RenderMetadata\ is made public with variant container support.

Sources/SwiftDocC/Model/Rendering/RenderNode · high confidence

The \Resources\, \Tile\, and \TutorialSection\ directive parsers now use a unified \Diagnostic\ type instead of the legacy \Problem\ type, simplifying error reporting and enabling solution suggestions directly on diagnostics. The old initializers accepting \DocumentationContext\ and \Problem\ arrays are deprecated in favor of new APIs that accept \DocumentationContext.Inputs\ and \FeatureFlags\, aligning with broader architectural changes to stop sharing global mutable state. Additionally, these directive types now expose an \introducedVersion\ property set to "5.5", making their availability information explicit for documentation consumers.

Sources/SwiftDocC/Semantics/Technology/Resources, Sources/SwiftDocC/Semantics/Tutorial/Tasks · high confidence

The Tutorial and XcodeRequirement semantic types have been refactored to conform to AutomaticDirectiveConvertible, replacing the previous manual DirectiveConvertible implementation. This change introduces \@DirectiveArgumentWrapped\ and \@ChildDirective\ property wrappers to declare arguments and child directives, removes the manual \init(from:source:for:in:problems:)\ parsing logic in favor of a centralized \validate\ method, and updates the internal diagnostic handling to use \Diagnostic\ instead of the deprecated \Problem\ type. For users, this represents an internal structural improvement to how tutorial metadata and requirements are parsed and validated, ensuring consistency with the broader directive system.

Sources/SwiftDocC/Semantics/Tutorial · high confidence

The \TutorialArticle\ and \Stack\ semantic models have been updated to adopt the \AutomaticDirectiveConvertible\ protocol and use the unified \Diagnostic\ system instead of the legacy \Problem\ type. This change introduces a new initializer signature that accepts \DocumentationContext.Inputs\ and \FeatureFlags\ directly, replacing the previous \bundle\ and \context\ parameters. Additionally, the \landmarks\ property now uses the \any\ existential type, and internal validation logic has been centralized into a \validate\ method. The code also reflects the renaming of 'Technology' to 'Tutorial Table of Contents' in parent checks and error messages, and updates the copyright year to 2026.

Sources/SwiftDocC/Semantics/TutorialArticle · high confidence

Tutorial render sections (including article body, intro, assessments, and task sections) now conform to the RenderJSONDiffable protocol, enabling the system to compute and report differences between render node versions. This change also adopts the SE-0335 existential any syntax for decoder/encoder initializers and adds Equatable conformance to these section types to support the diffing logic.

Sources/SwiftDocC/Model/Rendering/Tutorial Article, Sources/SwiftDocC/Model/Rendering/Tutorial/Sections · high confidence

DocC now uses a single \Diagnostic\ type to replace the previous \Problem\ wrapper, simplifying how issues are reported and handled. This change introduces structured solutions (fix-its) directly into diagnostics, allowing tools to present actionable fixes to users. Additionally, a new \DiagnosticFileWriter\ enables detailed diagnostic data to be written to a file for external tooling, and the console output can now be formatted specifically for IDEs or other parsers via the \formatConsoleOutputForTools\ option.

Sources/SwiftDocC/Infrastructure/Diagnostics · high confidence

The semantic analysis infrastructure in this module now uses a single \Diagnostic\ type for all validation errors, replacing the previous \Problem\ wrapper. This change simplifies how authors receive feedback: diagnostics are now emitted directly with richer context (such as \explanation\ and \solutions\) and are no longer wrapped in a separate container. The old \analyze\ methods accepting \problems: inout \[Problem\]\ are deprecated in favor of new signatures that accept \diagnostics: inout \[Diagnostic\]\, ensuring a consistent and more detailed error reporting experience for documentation authors.

Sources/SwiftDocC/Semantics/General Purpose Analyses · high confidence

The SwiftDocC semantic graph now uses SymbolKit's unified symbol graph representation, shifting from a local \SymbolKind.Swift\ enum to extensions on \SymbolGraph.Symbol.KindIdentifier\. This change introduces a \renderingIdentifier\ property that strips the language prefix (e.g., 'swift.') from symbol identifiers to maintain backward compatibility with existing render models, while also exposing a \swiftSymbolCouldHaveChildren\ property to determine symbol hierarchy capabilities directly on the identifier type.

Sources/SwiftDocC/Semantics/Graph · high confidence

The \bin/preview-docs\ script now targets the \DocCCommandLine\ module instead of \SwiftDocCUtilities\, reflecting the project's target consolidation, and the \bin/test\ script has been updated to build and test the \bin/benchmark\ and \bin/make-test-bundle\ auxiliary packages in CI. Additionally, the \bin/check-source\ script now enforces the removal of the term 'master' in source code, excludes \.docc-build\ directories from HTML checks, and the \bin/update-gh-pages-documentation-site\ script was added to automate documentation publishing. The legacy \bin/benchmark.swift\ and \bin/benchmark-diff.swift\ scripts were removed.

bin · high confidence

The Utility module has been reorganized with new files for collection diffing (CollectionChanges), feature flags (FeatureFlags), and file iteration (FileManagerProtocol+FilesSequence), while removing legacy Linux bundle shims and an internal logging utility. Concurrent processing in Collection+ConcurrentPerform.swift now uses Swift Concurrency (async/await) with improved task scheduling, and thread safety in LogHandle is enforced via a Synchronized wrapper. Additionally, the NearMiss utility now uses CollectionChanges to provide better symbol-link error suggestions, and the Synchronization type has been extended to support Windows, Android, FreeBSD, and OpenBSD platforms.

Sources/SwiftDocC/Utility · high confidence

The parsing logic for the Volume directive has been updated to use the new \DocumentationContext.Inputs\ and \Diagnostic\ types instead of the older \DocumentationBundle\, \DocumentationContext\, and \Problem\ types. This change aligns the Volume initializer with the broader migration to a unified diagnostic system and simplified input handling, ensuring that validation errors and warnings are now reported through the new \Diagnostic\ array. The old initializer is deprecated in favor of the new signature.

Sources/SwiftDocC/Semantics/Technology/Volume · high confidence

Added DictionaryData test bundle for symbol graph parsing; Added and updated tests for DocC command-line argument parsing; Added and updated utility tests for DocC; Added legacy test bundle for Swift DocC testing; Added test bundle for @Available directive with arbitrary platform support; Added test bundle for C++ union symbol kinds; Added test bundle for DefaultImplementations documentation; Added test bundle for HTTP request documentation; Added test bundle for alternate declarations; Added test bundle for anonymous topic groups; Added test bundle for availability override scenarios; Added test bundle for book-like documentation content; Added test bundle for documenting executable modules; Added test bundle for mixed manual/automatic curation with new metadata directives; Added test bundle for mixed-language framework link resolution; Added test bundle for mixed-language framework symbol graph relationships; Added test bundle for mixed-language framework with language refinements; Added test bundle for multi-curated documentation subtrees; Added test bundle for multi-language framework documentation; Added test bundle for multi-platform module extensions; Added test bundles for nested-type extension collisions and relative path ambiguity; Added test coverage for @DeprecationSummary directive handling; Added test coverage for DocC command-line actions and utilities; Added test coverage for DocC command-line utility components; Added test fixture for empty declaration fragments; Added test fixture for mixed-language error curation; Added test fixtures for @SupportedLanguage directive validation; Added test fixtures for extension symbol curation; Added test fixtures for legacy bundles and mixed-language symbol graphs; Added test fixtures for sample code and call-to-action metadata; Added test fixtures for snippet slicing and indentation; Added test resources for Swift DocC rendering and symbol graph validation; Added tests for @Links, @Row, @Small, and @TabNavigator directives; Added tests for DocC Preview Server request handling and live reload; Added tests for DocCCommon decoder and language set optimizations; Added tests for DocumentationContext link resolution, source language handling, and root page logic; Added tests for GroupedSequence and relocated BidirectionalMap tests; Added tests for LinkDestinationSummary decoding and summarization; Added tests for Markdown output rendering; Added tests for Out-Of-Process Reference Resolver V2 and new test utilities; Added tests for RenderNodeVariantOverridesApplier; Added tests for SourceRepository URL formatting; Added tests for directive index and reflection infrastructure; Added tests for documentation input discovery logic; Added tests for documentation semantics and directives; Added tests for full-page HTML rendering with custom headers and footers; Added tests for indexing and navigator index features; Added tests for infrastructure components; Added tests for inherited operator documentation in Swift DocC; Added tests for multi-language rendering, aside styles, and link title preservation; Added tests for rendering variant overrides and JSON patch operations; Added tests for the @Options directive semantics; Added tests for the generated curation writer; Added tests for the static HTML documentation formatter; Clean up unused keys in test bundle Info.plist files; Expanded test coverage for documentation model behaviors; Migrate link completion tests to Swift Testing; Refactored WebKit communication bridge tests and removed obsolete test files; Removal of argument parsing tests for Convert and Preview subcommands; Removal of legacy test utilities and fixtures; Removed PreviewServer test suite and utilities; Removed obsolete preview server request handler tests; Removed obsolete test bundle assets; Removed obsolete test suite files; Removed test fixture Swift files from TestBundle.docc; Tests updated for diagnostic system migration and new severity controls; Updated ConvertService and server tests to use new bundle info structure and added coverage for remote source and comment overrides; Updated benchmark tests to use async APIs and new metric types; Updated checker tests to use Swift Testing and Diagnostic API; Updated converter tests to use async context loading and simplified APIs; Updated coverage tests to use referencePath instead of usr; Updated semantic analysis tests to use the new Diagnostic API; Updated server tests to use synthetic file systems and expanded platform support; Updated signal-test-app to use DocCCommandLine and test SIGABRT; Updated symbol graph infrastructure tests to Swift Testing and modernized test helpers; Updated test bundle for duplicate output path diagnostics.

The project has upgraded its Swift tools version from 5.5 to 6.1, raising the minimum supported platforms to macOS 13 and iOS 16. This change includes significant dependency updates: swift-argument-parser is bumped to 1.4.0, swift-crypto to 3.15.1, and swift-nio to 2.92.2. Additionally, the build system now uses package traits to conditionally include SwiftNIO for the preview server, disabling it by default on unsupported platforms like Windows.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 63 → 58 (-4.1)
• Rubric changed (rubric-2026.09.11 → rubric-2026.09.18) — scores are not directly comparable.

• Code Health 83 → 83 (+0.4)
• Architecture 94 → 86 (-8.3)
• Maturity 54 → 52 (-1.6)
• Readiness 64 → 56 (-8.3)
• Security 83 → 83 (+0.0)
• Domain Modelling 90 → 90 (+0.0)
• Accessibility 66 → 66 (+0.0)
• Performance 66 (new)

• Dependency hygiene PARTLY measured — SwiftPM pinning read, dependency currency NOT established
• Documentation: no installation or build instructions (README.md)
• Documentation: no usage examples (README.md)
• Duplicated block (12 lines × 2) (Sources/SwiftDocC/Model/Rendering/RenderNodeTranslator.swift)
• Duplicated block (16 lines × 4) (Sources/DocCCommon/JSONDecoding/SymbolGraph+FastJSONDecodable.swift)
• Duplicated block (16–17 lines × 2) (Sources/DocCCommon/JSONDecoding/SymbolGraph+FastJSONDecodable.swift)
• Duplicated block (16–17 lines × 3) (Sources/DocCCommon/JSONDecoding/SymbolGraph+FastJSONDecodable.swift)
• Duplicated block (18 lines × 4) (Sources/DocCCommon/JSONDecoding/SymbolGraph+FastJSONDecodable.swift)
• Duplicated block (21 lines × 3) (Sources/DocCCommon/JSONDecoding/SymbolGraph+FastJSONDecodable.swift)
• Duplicated block (21–24 lines × 2) (Sources/DocCCommon/JSONDecoding/SymbolGraph+FastJSONDecodable.swift)
• Duplicated block (7 lines × 3) (Sources/DocCCommon/JSONDecoding/SymbolGraph+FastJSONDecodable.swift)
• Duplicated block (8 lines × 2) (Sources/DocCCommon/JSONDecoding/SymbolGraph+FastJSONDecodable.swift)
• Duplicated block (9 lines × 2) (Sources/DocCCommon/JSONDecoding/SymbolGraph+FastJSONDecodable.swift)
• Edited copy of a member (33 corresponding lines) (Sources/DocCCommon/JSONDecoding/SymbolGraph+FastJSONDecodable.swift)
• Edited copy of a member (35 corresponding lines) (Sources/DocCCommon/JSONDecoding/SymbolGraph+FastJSONDecodable.swift)
• Hotspot: Sources/DocCCommandLine/Action/Actions/Convert/ConvertFileWritingConsumer.swift (Sources/DocCCommandLine/Action/Actions/Convert/ConvertFileWritingConsumer.swift)
• Hotspot: Sources/DocCHTML/HTMLFormatter.swift (Sources/DocCHTML/HTMLFormatter.swift)
• Hotspot: Sources/DocCHTML/MarkdownRenderer.swift (Sources/DocCHTML/MarkdownRenderer.swift)
• Hotspot: Sources/SwiftDocC/Infrastructure/Link Resolution/PathHierarchy+TypeSignature.swift (Sources/SwiftDocC/Infrastructure/Link Resolution/PathHierarchy+TypeSignature.swift)
• Hotspot: Sources/SwiftDocC/Infrastructure/Topic Graph/AutomaticCuration.swift (Sources/SwiftDocC/Infrastructure/Topic Graph/AutomaticCuration.swift)
• …and 12 more

• Availability.addInSourceAvailability (cognitive 32) (Sources/SwiftDocC/Model/Availability.swift)
• Availability.addInSourceAvailability (cyclomatic 18) (Sources/SwiftDocC/Model/Availability.swift)
• Availability.finalizePlatformFallbacks (cognitive 18) (Sources/SwiftDocC/Model/Availability.swift)
• Availability.finalizePlatformFallbacks (cyclomatic 17) (Sources/SwiftDocC/Model/Availability.swift)
• Availability.isBeta (cognitive 17) (Sources/SwiftDocC/Model/Availability.swift)
• DeclarationsSectionTranslator.swift.postProcessTokens (cognitive 28) (Sources/SwiftDocC/Model/Rendering/RenderSectionTranslator/DeclarationsSectionTranslator.swift)
• DeclarationsSectionTranslator.swift.postProcessTokens (cyclomatic 16) (Sources/SwiftDocC/Model/Rendering/RenderSectionTranslator/DeclarationsSectionTranslator.swift)
• Duplicated block (10 lines × 4) (Sources/SwiftDocC/Model/Rendering/Diffing/DifferenceBuilder.swift)
• Duplicated block (11 lines × 2) (Sources/SwiftDocC/LinkTargets/LinkDestinationSummary+FastJSONDecodable.swift)
• Duplicated block (11–29 lines × 2) (Sources/SwiftDocC/Infrastructure/Link Resolution/PathHierarchy+PathComponent.swift)
• Duplicated block (12 lines × 2) (Sources/SwiftDocC/Model/Rendering/RenderNodeTranslator.swift)
• Duplicated block (12 lines × 3) (Sources/SwiftDocC/Semantics/Options/AutomaticArticleSubheading.swift)
• Duplicated block (13 lines × 2) (Sources/SwiftDocC/Infrastructure/Link Resolution/SnippetResolver.swift)
• Duplicated block (15 lines × 2) (Sources/DocCHTML/MarkdownRenderer.swift)
• Duplicated block (15 lines × 3) (Sources/DocCCommon/JSONDecoding/SymbolGraph+FastJSONDecodable.swift)
• Duplicated block (15–16 lines × 2) (Sources/DocCCommon/JSONDecoding/SymbolGraph+FastJSONDecodable.swift)
• Duplicated block (16 lines × 6) (Sources/DocCCommon/JSONDecoding/SymbolGraph+FastJSONDecodable.swift)
• Duplicated block (16–17 lines × 2) (Sources/DocCCommon/JSONDecoding/SymbolGraph+FastJSONDecodable.swift)
• Duplicated block (16–17 lines × 3) (Sources/DocCCommon/JSONDecoding/SymbolGraph+FastJSONDecodable.swift)
• Duplicated block (16–17 lines × 4) (Sources/DocCCommon/JSONDecoding/SymbolGraph+FastJSONDecodable.swift)
• …and 540 more

• 14 commits — 13 feature/other, 1 fixes

• Sources/SwiftDocC — 11 commits
• Tests/SwiftDocCTests — 2 commits
• Sources/DocCHTML — 1 commit

• fix: Fix miscellaneous symbol links and missing parameter documentation (#1664)
• change: Add initial implementation of a consolidated availability logic (#1674)
• change: Avoid verifying or modifying the symbol semantic's availability information (#1669)
• change: Change Boolean render availability properties to be non optional (#1672)
• change: Correctly strip ".docc" extension for display name (#1679)
• change: Deterministically render conformance lists (#1629)
• change: Faster decoding of link dependencies (#1662)
• change: Match documented parameter names to the declarations (#1663)
• change: Match the markdown output framework metadata to the module symbol name, where possible. (#1661)
• change: Minor tidying of spelling and whitespace in existing availability tests (#1673)
• change: Reduce some allocations across the build (#1659)
• change: Support unconditionally deprecated platform availability in static HTML output (#1670)
• change: Update documentation about Column alignment availability (#1668)
• change: updates the code block annotation to on by default (#1667)

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

swiftlang/swift-docc was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.