Proposal: Add -fgen-api-json flag to zig build docs for machine-readable documentation output

[xmov-vip]

Title: Proposal: Add -fgen-api-json flag to zig build docs for machine-readable documentation output

Problem

The current zig build docs command is invaluable for generating human-readable HTML documentation. However, the lack of a machine-readable output format creates a significant barrier for developers building modern tooling around Zig, such as:

• AI-powered coding assistants and chatbots
• Advanced IDE plugins and language servers
• Custom documentation browsers and search interfaces
• Automated code analysis and linting tools

These tools are currently forced to either:

1. Scrape the generated HTML, which is fragile, inefficient, and breaks with styling changes.
2. Re-parse the entire standard library source code using std.zig.Ast, duplicating the complex parsing work already performed by the documentation builder.

Proposed Solution

Add a new compiler flag, -fgen-api-json, to the zig build docs command. When enabled, this flag would direct the compiler to generate a comprehensive, machine-readable JSON representation of the API documentation alongside the traditional HTML output.

Suggested Flag Behavior:

• zig build docs -fgen-api-json: Generates a single, consolidated std-docs.json file.
• zig build docs -fgen-api-json=per_module: Generates a structured directory of JSON files (e.g., std/array_list.json, std/mem.json) for finer-grained consumption.

Desired Output Format (Conceptual):

The JSON output should provide structured data for all public declarations. For example, a function could be represented as:

{
  "name": "ArrayList.init",
  "signature": "fn init(allocator: std.mem.Allocator) ArrayList(T)",
  "documentation": "Creates a new ArrayList which will use the provided allocator for its internal memory.",
  "file": "lib/std/array_list.zig",
  "line": 123,
  "type": "fn",
  "parameters": [
    {
      "name": "allocator",
      "type": "std.mem.Allocator"
    }
  ],
  "return_type": "ArrayList(T)"
}

The same structured approach would apply to structs, enums, types, and other constructs, capturing their names, fields, methods, and documentation.

Benefits

1. Ecosystem Enablement: Dramatically lowers the barrier to creating high-quality, intelligent development tools that deeply understand the Zig standard library, fostering a richer ecosystem.
2. Robustness & Stability: Tools can rely on a stable, structured data interface maintained by the Zig compiler itself, eliminating the need for fragile scraping techniques or re-implementing complex AST parsing logic.
3. Performance: Building external tools and knowledge bases becomes a simple and efficient matter of parsing JSON, rather than processing heavy HTML or raw source code.
4. Official Source of Truth: The generated data is guaranteed to be perfectly synchronized with the official HTML documentation and the compiler's own understanding of the APIs.

This feature would be a powerful investment in the Zig ecosystem, making it significantly easier to build the next generation of developer tools around the language.

Let me know your thoughts on this proposal.

[xmov-vip]

Strategic Benefits of -fgen-api-json for Zig's Ecosystem & AI-Driven Development

Adding a -fgen-api-json flag to zig build docs is not a minor feature, but a strategic accelerator for the Zig ecosystem. It directly enables the next generation of developer tools by providing a machine-readable, authoritative data source for the entire standard library, eliminating the need for fragile HTML scraping or re-implementing complex AST parsing.

1. Drastically Lowers Barrier for Advanced Tooling
This feature would instantly empower creators to build robust LSPs, IDE plugins, AI assistants, and static analyzers. The development focus shifts from obtaining API data to innovating with it, rapidly enriching the Zig tooling landscape.

2. Ensures Ecosystem-Wide Consistency & Accuracy
All tools would derive their knowledge from a single source of truth—the Zig compiler itself. This guarantees consistency across tools and eliminates parsing errors, making the entire ecosystem more reliable and professional.

3. Positions Zig as the Ideal AI-Co-Development Platform
Zig’s philosophy aligns perfectly with AI-assisted programming:

• Explicitness & Simplicity: No hidden control flow, implicit allocations, or complex traits. AI can generate predictable, correct code.
• Predictable Performance: Code behaves as written. AI's algorithmic choices directly translate into expected runtime performance.
• Seamless C Interop: AI can leverage the entire C ecosystem without bindings, vastly expanding its capabilities.
• Power of comptime: AI can generate highly specialized, type-safe, and optimized code by leveraging compile-time execution.
• Cross-Compilation: Code generated for one target is easily portable, maximizing its utility.

Providing structured API data is the critical link that allows AI to fully understand and leverage these unique strengths. It transforms Zig from a language that is merely good for humans into the most predictable and powerful language for AI-assisted, high-performance development.

This creates a powerful feedback loop: Better data → Smarter AI tools → Improved developer experience → A stronger, growing ecosystem → Further language improvement. This proposal is an investment in making Zig the leading platform for the future of programming.