DocCGen

DocC-style documentation for C projects.

Overview

Doxygen is the conventional tool for generating API documentation for a C project. DocCGen brings the Markdown-based style and features of DocC to C projects.

C projects are documented using DocC syntax, a custom variant of Markdown that adds functionality for developer-specific documentation features, like cross-symbol linking, term-definition lists, code listings, and asides.

/// Creates an opaque color from its red, green, and blue components.
/// 
/// - Note: See ``Color`` for more information.
///
/// - Parameters:
///   - red: The red component, from 0 to 255.
///   - green: The green component, from 0 to 255.
///   - blue: The blue component, from 0 to 255.
/// - Returns: A fully opaque color with the given components.
Color color_make_opaque(
    uint8_t red, 
    uint8_t green, 
    uint8_t blue
);

Documentation is generated by naming the project's public-header root and module:

doccgen include --module SomeLib

DocCGen discovers the public headers under include, extracts their symbols, and writes SomeLib.doccarchive. Each discovered header is checked in isolation; a public header must parse on its own, with each #include resolved through the header root. A header that fails this check stops the run and reports the clang diagnostic. Pass --allow-non-self-contained to downgrade the failure to a warning.

Additional clang and docc flags are forwarded verbatim through -Xcc and -Xdocc; a flag that takes its own argument repeats the channel. The following renders a static site, resolving a vendored include path and a documentation build flag through clang, and a hosting base path through docc:

doccgen include --module SomeLib \
    --output-mode static-site --catalog SomeLib.docc \
    -Xcc -I -Xcc vendor/include \
    -Xcc -DSOMELIB_DOCS \
    -Xdocc --hosting-base-path -Xdocc SomeLib

Recurring configuration may be recorded in a .doccgen.json file in the working directory:

{
    "module"        : "SomeLib",
    "headerRoot"    : "include",
    "catalog"       : "SomeLib.docc",
    "exclude"       : ["**/*_private.h"],
    "outputMode"    : "static-site"
}

With a configuration file present, a project may be documented with doccgen alone. See Configuration for the full schema.

Tip

Use the doccgen --help command for more information.

Note

clang does not attach documentation comments to macro definitions. A documented macro's page and inbound links are generated, but its own prose is not rendered.

Configuration

Every setting may be given on the command line, in a configuration file, or both. A module name and a header root are required, from either source; everything else has a default.

Key	Type	Default	Command line
module	String	Required	--module
headerRoot	Path	Required	Positional argument
bundleVersion	String	1.0.0	--bundle-version
bundleIdentifier	String	The module name	--bundle-identifier
include	Array of globs	["**/*.h"]	--include, repeatable
exclude	Array of globs	[]	--exclude, repeatable
catalog	Path	None	--catalog
outputMode	archive, static-site	archive	--output-mode
outputPath	Path	<module>.doccarchive, or docs (static)	--output-path
clangFlags	Array of strings	[]	-Xcc, repeatable
doccFlags	Array of strings	[]	-Xdocc, repeatable
allowNonSelfContained	Boolean	false	--allow-non-self-contained

A command-line option overrides the configuration file's value for that setting wholesale, an array included: --exclude replaces the file's exclude list rather than adding to it. An option left off the command line says nothing, so the file's value stands. An empty list can therefore only be expressed in the file.

The two passthrough channels are the exception. clangFlags and doccFlags accumulate: the file's flags are passed first, followed by the command line's flags. Both clang and docc take the last value of a repeated flag, so a command-line flag wins any conflict with the file.

Glob patterns match against each header's path relative to the header root, and an exclude overrides an include regardless of pattern order.

A path in the configuration file resolves against the file's own directory; a path on the command line resolves against the current directory.

.doccgen.json is read from the working directory only, and is not searched for in parent directories. --config names a configuration file explicitly, and a --config path that does not exist stops the run rather than falling back to the default.

Note

An unrecognized key is an error, not a silent no-op.

Exit codes

Code	Meaning
0	Documentation generated.
1	General failure.
64	Missing or invalid configuration, unreadable header root, no matching headers, bad command-line argument.
69	clang or docc not found in the active toolchain.

64 and 69 are raised before any documentation is written, and both are fixed by correcting the invocation or the environment. 1 covers everything else: clang or docc exiting unsuccessfully, a header failing the self-containment check, and any failure DocCGen does not classify further.

Installation

Mint

mint install swift-developer-tools/DocCGen@<tag>

Note

The executable is installed into ~/.mint/bin, which must be on PATH.

Swift Package Manager

git clone --branch <tag> --depth 1 https://github.com/swift-developer-tools/DocCGen.git
cd DocCGen
swift package experimental-install -c release

Note

The executable is installed into ~/.swiftpm/bin, which must be on PATH.

Requirements

DocCGen resolves clang and docc from the active Xcode toolchain through xcrun. A full Xcode installation is required and must be the active toolchain, as reported by xcode-select -p.

Requirement	Minimum Version
Swift	6.3
macOS	13.0

License

DocCGen is licensed under the Apache License, Version 2.0.

See LICENSE for the complete license terms.