docc2json

A fast Go CLI tool that parses Apple's DocC JSON documentation output and converts it to a clean, structured JSON schema optimized for web documentation sites and SDKs.

Features

• Parses DocC JSON output from .doccarchive or processed documentation folders
• Generates custom SDK schema with full type information, method signatures, and documentation
• Comprehensive documentation extraction - extracts abstracts, discussions, examples, and code listings from DocC comments
• Filters by access level with optional --public-only flag
• Fast parallel processing of JSON files
• Rich metadata extraction including parameters, return types, async/throws modifiers
• Cross-reference resolution for type relationships and protocol conformances
• Automatic protocol unmangling - converts mangled Swift protocol names (e.g., s8SendableP, Se) to clean names (Sendable)
• Smart conformance filtering - filters out stdlib protocols while keeping custom protocols
• Flexible grouping options - group types by prefix or custom configuration
• Articles and tutorials support - optionally include documentation articles
• Navigation structure generation for easy website integration

Installation

Installation

# For Apple Silicon Macs
curl -L https://github.com/AppGram/docc2json/releases/download/v1.0.0/docc2json-darwin-arm64 -o docc2json
chmod +x docc2json
sudo mv docc2json /usr/local/bin/

Build from source

go build -o bin/docc2json ./cmd/docc2json

Install globally

go install ./cmd/docc2json

Usage

Basic Usage

# Convert full SDK documentation
docc2json -i ./docs/data -o output.json

# From a .doccarchive
docc2json -i ./AppGramSDK.doccarchive -o output.json

# Public API only
docc2json -i ./docs/data -o sdk-public.json --public-only

# With verbose logging
docc2json -i ./docs -o output.json -v

# Compact JSON output (no indentation)
docc2json -i ./docs -o output.json --compact

# Filter out specific protocols from conformances
docc2json -i ./docs -o output.json --filter-protocols "Se,ScA,objc"

# Group types by name prefix (e.g., Wish, WishStatus, WishFilters -> Wish group)
docc2json -i ./docs -o output.json --group-by-prefix

# Use custom grouping configuration
docc2json -i ./docs -o output.json --group-by-prefix --group-config ./group-config.yaml

# Include articles and tutorials
docc2json -i ./docs -o output.json --include-articles

# Complete example with all features
docc2json \
  -i ../iOS/AppGramSDK/docs/data \
  -o sdk.json \
  --include-articles \
  --group-by-prefix \
  --group-config ./group-config.yaml \
  --filter-protocols "Se,ScA,objc,SE,SQ,SH,SY,SL" \
  --keep-all-conformances \
  --verbose

Command-Line Flags

Flag	Short	Description	Default
--input	-i	Path to .doccarchive or docs/data folder (required)	-
--output	-o	Output JSON file path	output.json
--public-only	-p	Include only public API symbols	false
--module	-m	Module name (auto-detect if not provided)	auto-detected
--verbose	-v	Enable verbose logging	false
--compact	-	Output compact JSON (no indentation)	false
--filter-protocols	-	Comma-separated list of protocol names to exclude from conformances	-
--keep-all-conformances	-	Keep all conformances without filtering (for debugging)	false
--group-by-prefix	-	Group types by name prefix (e.g., Wish, WishFilters → Wish group)	false
--group-config	-	Path to YAML file with custom grouping configuration	-
--include-articles	-	Include documentation articles and tutorials	false
--version	-	Print version information	-

Protocol Conformances

The tool automatically processes protocol conformances with smart filtering:

Automatic Unmangling

Swift and Objective-C protocols often appear as mangled names in DocC output. The tool automatically converts these to clean names:

• s8SendableP, Se → Sendable
• SQ, s9EquatableP → Equatable
• SH, s8HashableP → Hashable
• s12IdentifiableP → Identifiable
• 7SwiftUI4ViewP → View
• objc → NSObjectProtocol
• ScA → NSSecureCoding
• And many more...

Automatic Filtering

By default, the tool filters out Swift standard library and framework protocols:

Filtered (won't appear in output):

• Sendable, Equatable, Hashable, Codable, Identifiable
• View, ObservableObject
• Error, CustomStringConvertible, etc.

Kept (will appear in output):

• Your custom protocols
• Third-party framework protocols
• Any protocol not in the stdlib list

Custom Filtering

Use --filter-protocols to exclude additional protocols:

# Filter out your internal protocols
docc2json -i ./docs -o output.json --filter-protocols "InternalProtocol,DebugOnly"

Debugging

To see all conformances without any filtering (useful for debugging):

docc2json -i ./docs -o output.json --keep-all-conformances --verbose

Type Grouping

The tool supports flexible grouping of types, protocols, and enums for better organization in documentation sites.

Automatic Prefix-Based Grouping

Use --group-by-prefix to automatically group types by their name prefixes:

docc2json -i ./docs -o output.json --group-by-prefix

This will group types like:

• Wish, WishStatus, WishFilters → Wish group
• Survey, SurveyMap, SurveyData → Survey group
• AppGramSDK, AppGramTheme, AppGramConfig → AppGram group

Custom Grouping with YAML Configuration

For more control, create a group-config.yaml file:

groups:
  # Feedback and Wishes
  Feedback:
    description: "User feedback and wish management"
    types:
      - Wish
      - WishFilters
      - Vote
      - Comment
    enums:
      - WishStatus
      - WishSortOption
    patterns:
      - "Wish*"
      - "*Wish"

  # Surveys
  Survey:
    description: "Survey and mapping functionality"
    patterns:
      - "Survey*"
    types:
      - SurveyMap
      - SurveyData

  # UI Components
  UI:
    description: "User interface components"
    patterns:
      - "*View"
      - "*Theme"
    protocols:
      - ViewConfigurable

Then use it with:

docc2json -i ./docs -o output.json --group-by-prefix --group-config ./group-config.yaml

Configuration options:

• types: Explicit list of type names
• protocols: Explicit list of protocol names
• enums: Explicit list of enum names
• patterns: Wildcard patterns ("Prefix*", "*Suffix", "*Infix*")
• description: Group description for documentation

Types not matching any group will be placed in an "Other" group.

Documentation Extraction

The tool fully extracts DocC documentation including:

• Abstract: Brief one-line description
• Discussion: Detailed explanation from ## Discussion sections
• Examples: Code examples from ## Example sections with full code listings
• Parameters: Parameter descriptions for methods
• Return values: Return value documentation
• Throws: Exception documentation

Example from Swift Source:

/// Represents a feedback item (wish) submitted by users.
///
/// ## Discussion
/// Wishes are user-submitted feedback items that can be voted on and commented on.
/// They represent feature requests, bug reports, or other feedback.
///
/// ## Example
/// ```swift
/// let wish = Wish(
///     id: "wish123",
///     title: "Dark mode support",
///     description: "Please add dark mode"
/// )
/// ```
public struct Wish { ... }

Extracted JSON:

{
  "name": "Wish",
  "description": {
    "abstract": "Represents a feedback item (wish) submitted by users.",
    "discussion": "Wishes are user-submitted feedback items that can be voted on and commented on. They represent feature requests, bug reports, or other feedback.",
    "examples": [{
      "title": "Example",
      "code": "let wish = Wish(\n    id: \"wish123\",\n    title: \"Dark mode support\",\n    description: \"Please add dark mode\"\n)"
    }]
  }
}

Articles and Tutorials

Include documentation articles and tutorials with --include-articles:

docc2json -i ./docs -o output.json --include-articles

This will include:

• Getting started guides
• Tutorials
• Conceptual documentation
• Best practices articles

Output Schema

The tool generates a JSON file with the following structure:

{
  "schemaVersion": "1.0.0",
  "metadata": {
    "sdkName": "AppGramSDK",
    "platform": "iOS",
    "language": "swift",
    "generatedAt": "2025-12-28T10:30:00Z"
  },
  "modules": [{
    "name": "AppGramSDK",
    "types": [/* classes, structs, actors */],
    "protocols": [/* protocols */],
    "enums": [/* enumerations */]
  }],
  "navigation": {
    "categories": [
      {
        "title": "Types",
        "items": ["AppGramSDK", "Configuration", ...]
      }
    ]
  }
}

Type Representation

Each type includes:

• kind: "class", "struct", or "actor"
• name: Type name
• access: "public", "internal", or "private"
• declaration: Full Swift declaration
• conformances: Protocols the type conforms to
• inheritance: Parent classes
• properties: Array of property definitions
• methods: Array of method definitions
• initializers: Array of initializers
• description: Documentation object containing:
  • abstract: Brief description
  • discussion: Detailed explanation
  • examples: Code examples with titles
  • returnValue: Return value documentation (for methods)
  • throws: Exception documentation (for methods)
• topicSections: Grouped navigation structure

Method Representation

Each method includes:

• name: Method name
• access: Access level
• isStatic: Whether it's a static/class method
• isAsync: Whether it's async
• throws: Whether it throws
• declaration: Full method signature
• signature: Structured signature with:
  • parameters: Array with label, name, type, optionality, descriptions
  • returnType: Return type
  • keywords: Swift keywords (func, static, async, etc.)

Enum Representation

Each enum includes:

• cases: Enum cases with descriptions
• properties: Computed properties
• methods: Instance and static methods
• conformances: Protocol conformances

Protocol Representation

Each protocol includes:

• requirements: Required methods, properties, and initializers
• inheritance: Inherited protocols
• conformingTypes: Types that conform to this protocol

Example Output

{
  "kind": "class",
  "name": "AppGramSDK",
  "access": "public",
  "declaration": "final class AppGramSDK",
  "conformances": ["Sendable"],
  "properties": [{
    "name": "shared",
    "type": "AppGramSDK",
    "isStatic": true,
    "access": "public",
    "declaration": "static let shared: AppGramSDK"
  }],
  "methods": [{
    "name": "configure",
    "declaration": "func configure(projectId: String, baseURL: String, theme: AppGramTheme?)",
    "signature": {
      "parameters": [
        {
          "label": "projectId",
          "type": "String",
          "isOptional": false
        },
        {
          "label": "baseURL",
          "type": "String",
          "isOptional": false
        },
        {
          "label": "theme",
          "type": "AppGramTheme",
          "isOptional": true
        }
      ],
      "returnType": "Void",
      "async": false,
      "throws": false
    }
  }]
}

Performance

Tested on AppGramSDK documentation (38,618 files):

• Parsing: ~0.4 seconds (parallel)
• Transformation: ~0.03 seconds
• Total: < 1 second
• Output size:
  • Types only: ~756KB for 129 symbols (103 types, 8 protocols, 18 enums)
  • With articles: ~1.2MB for 129 symbols + 92 articles

Architecture

docc2json/
├── cmd/docc2json/          # CLI entry point
├── internal/
│   ├── parser/             # DocC JSON parsing
│   │   ├── file_walker.go
│   │   ├── docc_parser.go
│   │   ├── token_builder.go
│   │   └── reference_resolver.go
│   ├── models/
│   │   ├── docc/           # DocC JSON structures
│   │   └── sdk/            # Output SDK structures
│   ├── transformer/        # DocC → SDK transformation
│   ├── filter/             # Access level filtering
│   └── writer/             # JSON output writer

How It Works

1. File Walking: Locates and collects all .json files in the DocC output
2. Parallel Parsing: Parses JSON files concurrently using goroutines
3. Token Reconstruction: Rebuilds method signatures from DocC's token arrays
4. Reference Resolution: Resolves cross-references between symbols
5. Access Filtering: Filters symbols based on access level (if --public-only)
6. Transformation: Converts DocC schema to custom SDK schema
7. JSON Output: Writes formatted JSON to the specified path

Tested With

• AppGramSDK - 38,618 documentation files, 129 symbols + 92 articles
• Swift 5.9+ DocC output
• DocC schema version 0.3.0
• iOS SDK documentation with full discussion and example extraction

Requirements

• Go 1.21 or higher
• DocC generated documentation (.doccarchive or processed docs/ folder)

Dependencies

• spf13/cobra - CLI framework
• uber-go/zap - Structured logging

Use Cases

• Documentation Websites: Generate JSON for custom documentation sites
• IDE Integration: Provide autocomplete and inline docs
• SDK Analysis: Programmatically analyze SDK structure
• Cross-Platform Docs: Generate documentation for other platforms

Recent Improvements

v1.1.0 (2025-12-28)

• Fixed Discussion extraction: Corrected heading text extraction from DocC JSON to properly capture Discussion, Example, and other documentation sections
• Added flexible grouping: Support for automatic prefix-based grouping and custom YAML configuration
• Articles support: Optional inclusion of documentation articles and tutorials
• Enhanced documentation: Full extraction of abstracts, discussions, and code examples from DocC comments

Key Bug Fixes

• Discussion sections: Fixed issue where DocC heading text was incorrectly extracted from InlineContent instead of Text field, causing Discussion and Example sections to be lost

License

MIT License

Author

Built by AppGram for converting iOS SDK documentation to web-friendly JSON format.

Version

1.1.0 - Enhanced documentation extraction and flexible grouping (2025-12-28)