Stig

Purpose

Stig is a modern C/C++ documentation generator that parses Doxygen-style comments using tree-sitter and generates markdown/mdbook/JSON/HTML output. It provides Standardese-compatible features for advanced documentation control, cross-references, coverage reporting, and CI/CD integration.

Key Features:

• 🚀 Fast tree-sitter parsing (no libclang)
• 📚 Multiple output formats (markdown, mdbook, JSON, HTML)
• 🔗 Smart cross-references with @ref tags
• 📊 Coverage reports and linting
• 👀 Watch mode with live preview
• 🔧 CMake and GitHub Actions integration
• 🌐 Compiler Explorer (Godbolt) links

Comment Formats

Block Comments (Preferred for complex docs)

/**
 * @brief Brief one-line description.
 * 
 * Detailed description spanning multiple lines.
 * Explain the purpose, behavior, and usage.
 * 
 * @param name Description of parameter
 * @return Description of return value
 */

Triple-Slash (Preferred for simple docs)

/// Brief description of the function.
/// @param x Description of x
/// @return Description of return
int square(int x);

Inline Comments (For struct/enum members)

struct Point {
    int x;  /**< X coordinate */
    int y;  ///< Y coordinate
};

enum Color {
    RED = 0,    /**< Red color */
    GREEN = 1,  ///< Green color
};

Command Prefix

Both @command and \command syntax are supported:

/// \brief Brief description
/// \param x The input value
/// \return The result

Supported Tags

Basic Tags

Exception & Condition Tags

Template & Return Value Tags

C++ Standard-Style Sections

Code Examples & Snippets

Cross-References & Links

Diagrams

Testing & Tracking

Entity Commands (Standardese-compatible)

Advanced Features

Cross-References

Use @ref to create links to other symbols or pages:

/**
 * @brief Processes a point
 * @param p A @ref Point to process
 * @return See @ref Result for details
 * 
 * This function uses @ref Point::transform() internally.
 * For more info, see @ref geometry_page "the geometry guide".
 */
Result process(Point p);

Generates: [Point](#point), [the geometry guide](geometry_page.md)

External Code Snippets

Include code from external files:

/**
 * @brief Example usage
 * @snippet examples/basic.cpp basic_usage
 */
void example();

In examples/basic.cpp:

//! [basic_usage]
Point p{10, 20};
p.transform(Matrix::identity());
//! [basic_usage]

Custom Pages

Create standalone documentation pages:

/**
 * @page getting_started Getting Started Guide
 * 
 * ## Installation
 * 
 * Download and install the library...
 * 
 * ## Basic Usage
 * 
 * See @ref Point and @ref Transform for core types.
 */

TODO/Bug Tracking

Track issues directly in code:

/// @brief Process data
/// @todo Optimize for large datasets
/// @bug Crashes with empty input (issue #123)
void process(const Data& data);

Generates separate TODO.md and BUGS.md pages.

Test References

Link to test cases:

/**
 * @brief Validates input
 * @test test_validate_basic
 * @test test_validate_edge_cases
 */
bool validate(const Input& input);

Generates TESTS.md with links to test files.

Mermaid Diagrams

Embed diagrams directly in documentation:

/**
 * @brief State machine implementation
 * 
 * @mermaid
 * stateDiagram-v2
 *     [*] --> Idle
 *     Idle --> Processing
 *     Processing --> Done
 *     Done --> [*]
 * @endmermaid
 */
class StateMachine { };

Entity Command Examples

Grouping Functions

/// @group getters Getter Functions
/// @brief Gets the X coordinate
/// @return The X value
int get_x();

/// @group getters
/// @brief Gets the Y coordinate
int get_y();

/// @group setters Setter Functions
/// @brief Sets the X coordinate
/// @param x The new X value
void set_x(int x);

Synopsis Override

/// @brief Process variadic arguments
/// @synopsis void process(Args... args)
/// @tparam Args Variadic template arguments
template<typename... Args>
void process(Args&&... args);

Excluding Entities

/// @exclude
void internal_helper();  // Not in documentation

/// @exclude return
/// @brief Factory function
/// @return Implementation-defined type
auto create_widget();  // Return type shown as "/* see below */"

Copying Documentation

/// @brief Base implementation
/// @param x Input value
/// @return Processed result
int base_function(int x);

/// @copydoc base_function
/// Additional notes for this variant.
int derived_function(int x);

File-Level Documentation

/**
 * @file geometry.hpp
 * @brief Core geometry types and algorithms.
 * @author John Doe
 * @since 1.0.0
 *
 * This file provides fundamental geometry primitives.
 */

Output Sections

/// @output_section Getter Functions
int get_x();
int get_y();

/// @output_section Setter Functions  
void set_x(int x);
void set_y(int y);

Docstring Guidelines for AI Agents

When adding docstrings to C/C++ code, follow these rules:

1. What to Document

• ALL public functions, methods, classes, structs, enums, typedefs, and macros
• ALL struct/enum members with inline comments
• File headers with @file and @brief
• Template parameters with @tparam

2. Comment Placement

• Place docstrings immediately before the declaration
• No blank lines between docstring and declaration
• Use inline comments (/**< */ or ///<) for struct/enum members

3. Required Tags

Functions/Methods:

/**
 * @brief What the function does (one line)
 * @param name Description for each parameter
 * @return What is returned (if not void)
 */

Template Functions:

/**
 * @brief What the function does
 * @tparam T Description of template parameter
 * @param value Description of parameter
 * @return What is returned
 */
template<typename T>
T process(T value);

Classes/Structs:

/**
 * @brief What this type represents
 * @tparam T Template parameter description (if templated)
 */
template<typename T>
class Container { };

File Headers:

/**
 * @file filename.h
 * @brief What this file contains
 * @author Author Name
 * @since 1.0.0
 */

4. Style Rules

• Start @brief with a verb (Computes, Returns, Creates, Initializes)
• Keep @brief to one line
• Add detailed description after blank line if needed
• Use @code blocks for usage examples on complex APIs
• Add @see or @ref for related functions/types
• Use @note for important behavior details
• Use @warning for dangerous operations
• Use @deprecated with replacement suggestion
• Use @group to organize related functions
• Use @exclude for internal helpers
• Use @ref for cross-references instead of plain text

5. Examples

Simple function:

/// Computes the absolute value of an integer.
/// @param n Input integer
/// @return Absolute value of n
int abs_value(int n);

Complex function with cross-references:

/**
 * @brief Searches for an element in the container.
 * 
 * Uses binary search algorithm. See @ref sort() for sorting requirements.
 * 
 * @param container The @ref Container to search
 * @param value The value to find
 * @return Iterator to the element
 * @retval end() If element not found
 * @retval begin() If container is empty
 * 
 * @complexity O(log n) binary search
 * @threadsafety Safe for concurrent reads
 * @see sort, find_if
 */
iterator find(const Container& container, const T& value);

Struct with members:

/**
 * @brief A rectangle defined by position and size.
 */
struct Rectangle {
    int x;      /**< X position of top-left corner */
    int y;      /**< Y position of top-left corner */
    int width;  ///< Width of the rectangle
    int height; ///< Height of the rectangle
};

Template class with example:

/**
 * @brief A 2D point in Cartesian coordinates.
 * @tparam T The scalar type (float, double, int)
 * 
 * @code{.cpp}
 * Point2<float> p{1.0f, 2.0f};
 * auto dist = p.distance(Point2<float>{3.0f, 4.0f});
 * @endcode
 * 
 * @see Vec2, Point3
 */
template<typename T>
class Point2 { };

Configuration (stig.toml)

Create a stig.toml in your project root:

title = "My Library API"
output = "docs"
format = "mdbook"  # markdown, mdbook, json, html
inputs = ["include/*.h", "include/*.hpp"]
language = "en"
generate_intro = true
grouping = "by_module"  # by_header, by_prefix, by_module, or flat
authors = ["Author Name"]

# Filtering options
blacklist_namespace = ["detail", "internal", "impl"]
blacklist_pattern = ["*_impl", "test_*"]
extract_private = false
extract_protected = true

# Output customization
[output]
show_source_location = true
show_access_specifiers = true
code_language = "cpp"
synopsis_style = "full"  # full, compact, minimal

# Custom section names (for localization)
[section_names]
parameters = "Parameters"
returns = "Returns"
throws = "Throws"
template_parameters = "Template Parameters"

# External documentation links
[[external_docs]]
prefix = "std::"
url_template = "https://en.cppreference.com/w/cpp/$$"

# Coverage options
[coverage]
min_coverage = 80
require_param_docs = true
require_return_docs = true

# Module organization
[[modules]]
name = "Core"
patterns = ["include/core/*.hpp"]
title = "Core Components"

[[modules]]
name = "Utils"
patterns = ["include/util/*.hpp"]
title = "Utility Functions"

Configuration Options

Running Stig

# Use stig.toml in current directory (generate is default)
stig

# Specify config file
stig -c path/to/stig.toml

# Generate specific format
stig generate -f mdbook -o docs/ --title "My API"

# Watch with live preview
stig generate --serve

# Check documentation (human-readable report)
stig check include/*.h

# Check with CI/CD-friendly output (file:line:col: severity: message)
stig check -f compiler include/*.h

# Check with minimum coverage threshold
stig check --min-coverage 80 include/*.h

# Check with strict mode (warnings as errors)
stig check --strict include/*.h

# Override config with CLI
stig generate -f mdbook -o docs/ --title "Custom Title"

CLI Reference

stig <COMMAND> [OPTIONS] <INPUT_FILES>...

COMMANDS:
    generate        Generate documentation (default if no subcommand)
    check           Check documentation coverage and quality
    preprocessor    Run as mdbook preprocessor
    help            Show help message
    version         Show version information

GENERATE OPTIONS:
    -o, --output <PATH>    Output file or directory (default: stdout)
    -f, --format <FMT>     Output format: markdown, mdbook, json, html
    --title <TITLE>        Book title (for mdbook/html format)
    -c, --config <FILE>    Config file path (default: stig.toml)
    -w, --watch            Watch for file changes and regenerate
    --serve                Watch mode + spawn mdbook serve for live preview
    --force                Force full rebuild, ignore cache
    -h, --help             Show help message

CHECK OPTIONS:
    -c, --config <FILE>    Config file path (default: stig.toml)
    -f, --format <FMT>     Output format: human, compiler, json
    --min-coverage <N>     Minimum coverage percentage (0-100)
    --strict               Treat warnings as errors
    -h, --help             Show help message

GLOBAL OPTIONS:
    -h, --help             Show help (use 'stig <command> --help' for details)
    -v, --version          Show version information

Automatic Filtering

Stig automatically excludes entities based on configuration:

Namespace Blacklist

By default, entities in detail, internal, and impl namespaces are excluded:

namespace mylib::detail {
    void helper();  // Excluded from docs
}

namespace mylib {
    void public_api();  // Included in docs
}

Pattern Blacklist

Entity names matching glob patterns are excluded:

blacklist_pattern = ["*_impl", "test_*", "internal_*"]

void process_impl();     // Excluded (matches *_impl)
void test_function();    // Excluded (matches test_*)
void process();          // Included

@exclude Tag

Use @exclude for fine-grained control:

/// @exclude
void internal_helper();  // Excluded

/// @exclude return
auto factory();  // Included, but return type hidden

Documentation Checking

The stig check command combines coverage analysis and linting into a single command with multiple output formats, designed for CI/CD integration.

Human-Readable Report (default)

stig check include/*.h

Output:

Documentation Coverage Report
=============================
Overall: 85% (42/50 entities documented)

By Type:
  Functions:    90% (27/30) [3 missing params, 2 missing returns]
  Classes:      80% (8/10)

Missing Documentation:
  include/api.h:
    - process() [line 42] - missing @param for 'flags'
    - validate() [line 58] - missing @return

Compiler-Style Output (for CI/CD)

stig check -f compiler include/*.h

Output (compatible with most IDEs and CI tools):

include/api.h:42:1: warning: missing @param for 'flags' 'process' (function)
include/api.h:58:1: warning: missing @return 'validate' (function)
include/api.h:75:1: warning: no documentation 'helper' (function)

stig: 3 documentation issue(s) found
stig: coverage 85% (42/50 entities documented)

JSON Output (for tooling)

stig check -f json include/*.h

Additional Options

# Set minimum coverage threshold (exit code 2 if below)
stig check --min-coverage 80 include/*.h

# Treat warnings as errors (exit code 2 if warnings found)
stig check --strict include/*.h

Exit Codes

• 0 - All checks passed
• 1 - Errors found (invalid references, etc.)
• 2 - Warnings found (with --strict) or coverage below threshold

What It Checks

• Missing @brief descriptions
• Undocumented parameters (@param)
• Missing return documentation (@return)
• Undocumented template parameters (@tparam)
• Broken cross-references (@see, @copydoc)
• Brief description length

Integration

CMake

find_package(Stig REQUIRED)

stig_add_docs(
    TARGET my_docs
    SOURCES include/*.hpp
    OUTPUT docs
    FORMAT mdbook
    TITLE "My Library API"
)

See cmake/README.md for details.

GitHub Actions

- name: Generate Documentation
  uses: ./.github/actions/stig-docs
  with:
    input: 'include/*.hpp'
    output: 'docs'
    format: 'mdbook'
    coverage: 'true'

See .github/actions/stig-docs/README.md for details.

mdbook Preprocessor

Add to book.toml:

[preprocessor.stig]
command = "stig preprocessor"

Use in markdown:

{{#stig api ../include/mylib.h}}
{{#stig function my_function}}

Rules for AI Agents

1. Every public API element MUST have a docstring
2. Use @brief for the first line description (start with a verb)
3. Document ALL parameters with @param
4. Document ALL template parameters with @tparam
5. Document return values with @return (unless void)
6. Use @retval for specific return value meanings
7. Use inline comments for struct/enum members
8. Add @code examples for complex APIs
9. Use @ref to link related items (not plain text)
10. Mark deprecated items with @deprecated and suggest alternatives
11. Use @group to organize related functions
12. Use @exclude for internal implementation details
13. Use @synopsis to simplify complex template signatures
14. Add @complexity and @threadsafety for performance-critical code
15. Use @test to link to test cases
16. Use @todo and @bug for tracking issues
17. Use @snippet for external code examples
18. Create @page for conceptual documentation
19. Add @mermaid diagrams for complex relationships
20. Use @copydoc to avoid documentation duplication