Jazzy: Swift and Objective-C documentation from the AST, not from source text

The problem Jazzy solves: documentation that matches the compiler's view of your code

Most documentation generators read your source files as text and parse comments with a grammar of their own. Jazzy takes a different route. The README states that instead of parsing source files, jazzy hooks into Clang and SourceKit to use the AST representation of your code and its comments. That distinction matters when your project uses macros, conditional compilation, or generics: the AST is what the compiler actually sees, so the generated pages reflect resolved declarations rather than a best-effort text scan.

The audience is narrow and specific. You are building a Swift or Objective-C project with Xcode or the Swift Package Manager, you already write documentation comments in your headers or source files, and you want output that matches the look and feel of Apple's official reference documentation post WWDC 2014. Jazzy is a command-line utility, so it slots into a Makefile, a Rakefile, or a CI job rather than into an editor plugin. If your project is not Apple-platform code, the AST hook has nothing to attach to.

How Jazzy builds docs: SourceKit, symbol graphs and output theming

There are two input paths. The default path takes source code and asks Clang or SourceKit for the AST, which is how both Swift and Objective-C projects are supported. The second path, described in the README as generating documentation from compiled Swift modules using their symbol graph, works from a built module instead of source. That second route is the reason Jazzy can document a framework you do not have sources for, or a module whose build is expensive enough that you would rather document a prebuilt artifact.

Either way, the pipeline needs a working build. The README is explicit that you need development tools to build the project you wish to document, and that Jazzy supports both Xcode and Swift Package Manager projects. A bare jazzy invocation from the project root builds the module first; the README's rule of thumb is that if your Swift module builds fine when you run xcodebuild or swift build without arguments from the root of your project, then running jazzy without arguments from the same place should succeed too.

On the output side, Jazzy renders Markdown comments, resolves symbol references written in backticks into links, understands DocC-style links, and renders LaTeX math through KaTeX. Configuration lives in a file named .jazzy.yaml by default, and jazzy --help config prints the exhaustive option list.

Installing Jazzy and generating your first documentation set

Jazzy ships as a Ruby gem. The README gives a single install command, with sudo bracketed as optional depending on how your Ruby is installed:

[sudo] gem install jazzy

Jazzy expects to be running on macOS. The README points to a Linux section for tips on running it there, so Linux is a documented but secondary path rather than the supported default. If the install fails, the README refers to an Installation Problems section for common causes.

Once installed, the first real use is deliberately undramatic: change into the root of a project that already builds, and run the command with no arguments.

jazzy

The README's stated expectation is that this succeeds when xcodebuild or swift build works without arguments from the same directory. If Jazzy documents the wrong module, pass --module to name the one you want. If that does not fix it and you are on Xcode, the README suggests passing extra arguments through to xcodebuild, for example:

jazzy --build-tool-arguments -scheme,MyScheme,-target,MyTarget

For a Swift Package Manager project, the README's own example selects the SPM build tool and forwards a Swift version flag:

jazzy \
  --module DeckOfPlayingCards \
  --swift-build-tool spm \
  --build-tool-arguments -Xswiftc,-swift-version,-Xswiftc,5

Objective-C is not automatic. The README lists three required parameters (--objc, --umbrella-header and --framework-root) plus optional ones including --sdk and --hide-declarations. To keep options out of the command line, put them in .jazzy.yaml in the project root; jazzy --help config documents every key.

Where Jazzy stops: Objective-C keywords, overload links and the macOS assumption

The README is unusually candid about one gap. Objective-C supports the same documentation keywords as Swift but with different syntax (for example @return instead of - returns:), and Jazzy currently does not support all Objective-C keywords listed in Apple's HeaderDoc guide. The supported set is @param, @return, @warning, @see, @note, @code, @endcode and @c. If your Objective-C headers lean on other HeaderDoc tags, those annotations will not render as structured sections.

DocC-style links are supported but with a stated limit. A link of the form <doc:method(_:)-e873> targets a specific overload, and the README says Jazzy cannot tell which overload you intend and links to the first one. For APIs with several overloads of the same name, the generated link may point somewhere other than your comment implies.

The platform constraint is the other boundary. Jazzy expects macOS, and while the README offers Linux tips, that path is not the default. A Linux CI runner that has never been checked against those tips is a plausible source of failures that have nothing to do with your source code. Finally, Jazzy documents Swift and Objective-C only. Nothing in the README suggests it can be pointed at another language.

Jazzy compared with DocC, and when the difference decides the choice

DocC is Apple's own documentation compiler and the obvious reference point, since Jazzy explicitly targets the post-WWDC 2014 Apple reference look. The difference is in where each tool sits in the toolchain. DocC is part of Apple's developer tooling and is invoked through Xcode or the Swift toolchain; Jazzy is a Ruby gem installed with gem install jazzy and driven from a shell, which is why it can be scripted into a Rakefile or a CI step the same way any other command-line tool can. Jazzy also accepts Objective-C projects through --objc, --umbrella-header and --framework-root, and it can read compiled Swift modules via their symbol graph rather than source.

The trade-off runs the other way too. Jazzy's DocC-link support is partial by its own documentation: it resolves a doc: link to the first matching overload rather than the one you named. If your documentation depends on precise overload targeting, that is a reason to use the tool that owns the link syntax. If your project is Objective-C, or you want documentation generation as one more shell command in an existing pipeline, Jazzy's approach is the one that fits.

Maintenance, licence and what an upgrade actually costs

The repository is not archived, and the last push was on 2026-09-14, which places it within the last six months of the date used for this assessment. Release cadence is slow and irregular: v0.15.2 in September 2024, v0.15.3 in October 2024, then v0.15.4 in October 2025. A team pinning Jazzy should expect roughly annual releases rather than a steady stream, and should read CHANGELOG.md before moving between them.

The practical upgrade cost is low but not zero, because Jazzy is a gem with a single install command and no runtime service. The real dependency is the toolchain underneath it: Jazzy needs a project that builds, so an Xcode or Swift version bump that breaks your build breaks documentation generation too, independently of any Jazzy release. Budget for that, not for Jazzy churn.

Jazzy is MIT licensed, which is permissive and imposes no copyleft obligation on your documentation output. This is a description of the licence identifier in the repository, not legal advice; if your organisation has rules about vendored gems or generated artifacts, run the question past whoever handles that.

Editorial conclusion

Adopt Jazzy if you ship a Swift or Objective-C library or app and want reference documentation that mirrors Apple's post-WWDC 2014 layout, with cross-references and LaTeX math rendered through KaTeX. Do not adopt it for non-Apple languages, for Linux-only CI without checking the Linux notes in the README, or if you expect DocC's own link resolution: Jazzy states it cannot tell which overload a doc: link intends and links to the first one. Before committing, verify that a bare jazzy run in your project root builds the module you expect, and if it picks the wrong one, check whether --module or extra --build-tool-arguments fix it.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. realm/jazzy on GitHub
5. Releases