jazzy: docs built from Clang's AST, with an Objective-C caveat and an overload caveat

It borrows Clang's AST instead of writing a parser in Ruby

The design decision is stated in one sentence and everything else follows from it. Rather than parsing your source files, jazzy hooks into Clang and SourceKit to use the AST representation of your code and its comments, which the page says is for more accurate results. The repository backs that up structurally: there is a SourceKitten directory beside the Ruby library and a submodules file, so the work of understanding Swift and Objective-C syntax is delegated rather than reimplemented. The README says this is for more accurate results.

The output is deliberately imitating Apple's reference documentation

The stated goal is that the output matches the look and feel of Apple's official reference documentation, post the 2014 developer conference. That claim is checkable, because the page shows the exact invocation used for a real project, with flags for the author, the source host and its URL, a version, the module, a root URL for links, an output directory and a theme directory. A second example covers a project built with the Swift package manager, and a third shows an Objective-C project. So the tool is not a generic documentation generator with an Apple skin; it is a renderer for one house style, and the theme flag is how you change the colours. If your project has an existing theme, that flag is the integration point, and everything else about the output, down to the symbol link syntax, follows Apple's conventions.

Objective-C support covers a named subset of the documentation tags

Both languages use documentation keywords written in markdown, and the same concepts are spelled differently: in Swift you would write a returns marker, in Objective-C you write the at-return tag. That part is manageable. The part to read carefully is the note that jazzy does not support all Objective-C keywords listed in Apple's documentation, and the page then enumerates exactly which ones work: at-param, at-return, at-warning, at-see, at-note, at-code, at-endcode and at-c. So a mixed codebase whose existing headers use the rest of Objective-C's documentation vocabulary will not get support for those tags. If you are migrating a large Objective-C project, that list is the acceptance criterion to test against before you commit to the tool.

Cross-reference syntax is rich, and overload links pick the first match

Link generation is where the page spends most of its detail, and the mechanism is simple: a symbol name in backticks becomes a link. From there the syntax grows. A plain class name links to the class, a method with its parameter label links to that method, a method with an ellipsis is shortcut syntax for the same, and a bare method name links from one member's documentation to another in the same class. Objective-C gets its own bracketed forms, with or without a leading minus sign. The limitation is in DocC-style links. A double-backtick path such as a class, a slash and a method with its parameters resolves correctly, but a disambiguated link with a suffix hash is documented plainly: jazzy cannot tell which overload you intend and links to the first one. So in an API with heavy overloading, links will be right and quietly point at the wrong declaration.

Configuration lives in a YAML file, and one flag decides which module you document

Most projects configure jazzy rather than typing it. Options for your documentation go in a configuration file, named .jazzy.yaml by default, and the page points at a help invocation for the exhaustive list of everything available. On the command line the common problem is documented too. If your Swift module is the first thing your project builds and it builds cleanly with the build tool from the project root, then running jazzy with no arguments from that same root should also succeed. If it documents the wrong module, there is a flag for that, and if that does not help under Xcode you can pass extra arguments through to the underlying build tool, for example a scheme and a target. The consequence is that a working setup is mostly one YAML file plus, at most, two command line overrides.

It can document a compiled module through its symbol graph

There is a second way to point jazzy at code, and it is the one that matters when sources are not available. Alongside source documentation, jazzy can generate documentation from compiled Swift modules using their symbol graph. That is a real capability rather than a fallback, because a symbol graph is what the toolchain emits for a built module, so a binary framework or a module you depend on can be documented without vendoring its source. The requirement section explains why it works in practice: you need the development tools for the project you wish to document, and jazzy supports both Xcode projects and Swift package manager projects. So the tool inherits the toolchain's expectations, which is a feature for consistency and a constraint for environments that build headlessly.

Installation is one gem command and the rest is troubleshooting

The short version is a single RubyGems command, with the sudo prefix optional depending on how Ruby was installed:

[sudo] gem install jazzy

Everything else on the page exists to resolve what happens after that. Jazzy expects to be running on macOS, with a separate section offering tips for running it on Linux, and it needs the development tools for the project you are documenting. There is a section dedicated to installation problems, and another for multiple modules. Release history is unhurried rather than absent: 0.15.3 in October 2024, 0.15.4 in October 2025, and 0.15.5 on 2026-10-01, with the last push on the default branch the same day. The repository is MIT licensed, carries a contributor covenant with a reporting address, and has a dedicated ObjectiveC.md file for Objective-C.

Editorial conclusion

Adopt it if you publish API documentation for a Swift or Objective-C project and want output that matches Apple's reference pages without building DocC. Do not adopt it expecting DocC feature parity: the Objective-C tag support is a named subset, and overloaded symbol links point at the first match. Before your first run, confirm the module your project builds first is the one jazzy picks, because the documented fix is passing the module and build tool arguments explicitly or setting them in the configuration file.

Frequently asked questions

Official sources

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