docc2json

Another major feature group is the intelligent processing of protocol conformances. docc2json automatically unmangles Swift protocol names, converting cryptic identifiers like `s8SendableP` into readable names such as `Sendable`. It also includes smart conformance filtering that removes standard library protocols (e.g., Equatable, Hashable, Codable) from output by default, keeping only custom and third-party protocols relevant to the user's SDK. This eliminates clutter and focuses documentation on what is unique to the project. Users can customize this filtering further using the --filter-protocols flag to exclude additional protocols, or use --keep-all-conformances for debugging. The combination of automatic unmangling and smart filtering significantly cleans up the output schema, making it more useful for documentation sites that highlight custom protocol adoptions without noise from ubiquitous system protocols.

docc2json provides flexible type grouping to organize documentation for better readability. Automatic prefix-based grouping (--group-by-prefix) clusters types by their name prefixes (e.g., Wish, WishStatus, WishFilters into a Wish group), creating logical sections. For more control, a YAML configuration file can define custom groups with explicit type lists, patterns using wildcards, and group descriptions. The output schema includes modules containing types, protocols, and enums, each with full documentation, methods, properties, and conformances. Additionally, a navigation structure is generated for easy website integration. Beyond JSON output, the tool includes a json2docs subcommand that converts generated JSON into Markdown or MDX files, suitable for static site generators like Docusaurus or Next.js, with optional YAML frontmatter.

The tool's workflow follows a structured pipeline. First, file walking locates all JSON files in the DocC output directory. These files are then parsed concurrently using goroutines, which dramatically reduces processing time for large archives. Next, token reconstruction rebuilds method signatures from DocC's internal token arrays, and reference resolution resolves cross-references between symbols. Access filtering then removes symbols based on the chosen access level. The core transformation step converts the DocC schema into a custom SDK schema, mapping types, methods, properties, and documentation into a consistent format. Finally, the result is written to a formatted JSON file. The architecture separates concerns into packages for parsing, transformation, filtering, and writing, making the tool maintainable and extensible for future DocC schema versions.

docc2json enables several concrete scenarios. For documentation websites, developers can generate a complete JSON snapshot of an iOS SDK and wire it into a custom frontend or static site, providing searchable API references. IDE integration becomes straightforward: plugins can consume the JSON to offer autocomplete and inline documentation within editors. SDK analysis tasks, such as programmatically checking API surface changes or generating changelogs, are simplified by having a structured data source. Cross-platform documentation can be unified by converting DocC output into files suitable for Markdown-based documentation systems. The primary outcome is a dramatic reduction in time spent on documentation maintenance—from hours of scripting to seconds of CLI execution—while preserving documentation accuracy and enhancing discoverability for end users.

docc2json is built for iOS and macOS developers, SDK authors, and documentation engineers who use Apple's DocC for their library documentation. It runs on macOS and Linux and requires Go 1.21 or higher. The tool is open source under the MIT license, and installation is available via prebuilt binaries for Apple Silicon or building from source. It is tested with Swift 5.9+ DocC output, including large SDKs with tens of thousands of files. In summary, docc2json provides a direct path from Xcode's DocC to web-ready JSON, delivering a clean, structured, and deployable format that empowers teams to present their SDK documentation exactly how they want, without manual reformatting or reliance on proprietary hosting.