From Prototype to Product: MrDocs in 2025

Portrait of Alan de Freitas Alan de Freitas · Oct 28, 2025

In 2024, the project was a fragile prototype. It documented Boost.URL, but the CLI, configuration, and build process were unstable. Most teams could not run it without direct help from the core group. That unstable baseline is the starting point for this report.

In 2025, we moved the codebase to minimum-viable-product shape. I led the releases that stabilized the pipeline, aligned the configuration model, and documented the work in this report to support a smooth leadership transition. This post summarizes the 2024 gaps, the 2025 fixes, and the directions for the next phase.

System Overview

MrDocs is a C++ documentation generator built on Clang and LLVM. It parses source with full language fidelity, links declarations to their comments, and produces reference documentation that reflects real program structure—templates, constraints, and overloads included.

Traditional tools often approximate the AST. MrDocs uses the AST directly, so documentation matches the code and modern C++ features render correctly.

Unlike single-purpose generators, MrDocs separates the corpus (semantic data) from the presentation layer. Projects can choose among multiple output formats or extend the system entirely: supply custom Handlebars templates or script new generators using the plugin system. The corpus is represented in the generators as a rich JSON-like DOM, enabling integration with other build systems, documentation frameworks, or IDEs.

From the user’s perspective, MrDocs behaves like a well-engineered CLI utility. It accepts configuration files, supports relative paths, includes deterministic build options, and reports warnings in a controlled, compiler-like fashion. For C++ teams transitioning from Doxygen, the command structure is somewhat familiar, but the internal model is designed for reproducibility and correctness. Our goal is not just to render reference pages but to provide a reliable pipeline that any C++ project seeking modern documentation infrastructure can adopt.

2024: Lessons from a Fragile Prototype

MrDocs entered 2024 as a proof of concept built for Boost.URL. It could walk one or two curated codebases and produce Antora pages, but the workflow stopped there. The CLI exposed only the scenarios we needed. Configuration options lived in internal notes. The only dependable build path was the script sequence we used inside the Alliance. External users hit errors and missing options almost immediately.

Stability was just as fragile: We had no sanitizers, no warnings-as-errors, and inconsistent CI hardware. The binaries crashed as soon as they saw unfamiliar code. The pipeline worked only when the input looked like Boost.URL. Point it at different templates or a library with heavy Concepts usage and it would segfault before extraction finished. Each feature landed as a custom patch, so logic duplicated across generators, and fixing one path broke another.

Early releases: Release v0.0.1 captured that prototype: the early Handlebars engine, the HTML generator, the DOM refactor, and a list of APIs that only the core team could drive. v0.0.2 added structured configuration, automatic compile_commands.json, and better SFINAE handling, but the tool was still insider-only.

Leadership transition: Late in 2024 I became project lead with two priorities: document the gaps and describe the true limits of the system. That set the 2025 baseline—a functional prototype that needed coherence, reproducibility, and trust before it could call itself a product.

What 2025 later fixed were the weaknesses we saw here: configuration coherence, generator unification, schema validation, and warning governance were all missing. The CLI, configuration files, and code drifted from each other. Generators evolved independently with duplicated templates and inconsistent naming. Editors had no schema to lean on, so validation and completion were impossible. Extraction rules were ad hoc, which made the output incomplete. CI ran on an improvised matrix with no caching, sanitizers, or coverage, so regressions slipped through. That was the starting point.

Summary: 2024 produced a working demo, not a reproducible system. Each success exposed another weak link and clarified what had to change in 2025.

In short:

  • 2024 left us with a working prototype but no coherent architecture.
  • The system could demonstrate the concept, but not sustain or reproduce it.
  • Every improvement exposed another weak link, and every success demanded more structure than the system was built to handle.
  • It was a year of learning by exhaustion—and setting the stage for everything that came next.

2025: From Prototype to MVP

I started the year with a gap analysis that compared MrDocs to other C++ documentation pipelines. From that review I defined the minimum viable product and three priority tracks. Usability covered workflows and surface area that make adoption simple. Stability covered deterministic behavior, warning governance, and CI discipline. Foundation covered configuration and data models that keep code, flags, and documentation aligned. The 2025 releases followed those tracks and turned MrDocs from a proof of concept into a tool that other teams can adopt.

  • v0.0.3 — Consistency. We replaced ad-hoc behavior with a coherent system: a single source of truth for configuration kept CLI, config files, and docs in sync; generators and templates were unified so changes propagate by design; core semantic extraction (e.g., concepts, constraints, SFINAE) became reliable; and CI hardened around reproducible, tested outputs across HTML and Antora.
  • v0.0.4 — Foundation. We introduced precise warning controls and a family of extract-* options to match established tooling, added a JSON Schema for configuration (enabling editor validation/autocomplete), delivered a robust reference system and Javadoc metadata integration, brought initial inline formatting to generators, and simplified onboarding with a cross-platform bootstrap script. CI gained sanitizers, coverage checks, modern compilers, and relocatable builds.
  • v0.0.5 — Stabilization. We redesigned documentation metadata to support recursive inline elements, enforced safer polymorphic types with optional references and non-nullable patterns, and added user-facing improvements (sorting, automatic compilation database detection, quick reference indices, improved namespace/overload grouping, LLDB formatters). The website and documentation UI were refreshed for accessibility and responsiveness, new demos (including self-documentation) were published, and CI was further tightened with stricter policies and cross-platform bootstrap enhancements.

Together, these releases executed the roadmap derived from the initial gap analysis: they aligned the moving parts, closed the most important capability gaps, and delivered a stable foundation that future work can extend without re-litigating fundamentals.

v0.0.3: Enforcing Consistency

v0.0.3 is where MrDocs stopped being a collection of one-off special cases and became a coherent system. Before this release, features landed in a single generator and drifted from the others; extraction handled only the narrowly requested pattern and crashed on nearby ones; and options were inconsistent—some hard-coded, some missing from CLI/config, with no mechanism to keep code, docs, and flags aligned.

What changed: The v0.0.3 release fixes this foundation. We introduced a single source of truth for configuration options with TableGen-style metadata: docs, the config file, and the CLI always stay in sync. We added essential Doxygen-like options to make basic projects immediately usable and filled obvious gaps in symbols and doc comments.

We implemented metadata extraction for core symbol types and their information—such as template constraints, concepts, and automatic SFINAE detection. We unified generators and templates so changes propagate by design, added tagfile support and “lightweight reflection” to documentation comments as lazy DOM objects and arrays, and extended Handlebars to power the new generators. These features allowed us to create the initial version of the website and ensure the documentation is always in sync.

Build and testing discipline: CI, builds, and tests were hardened. All generators were now tested, LLVM caching systems improved, and we launched our first macOS release (important for teams working on Antora UI bundles). All of this long tail of performance, correctness, and safety work turned “works on my machine” into repeatable, adoptable output across HTML and Antora.

v0.0.3 was the inflection point. For the first time, developers could depend on consistent configuration, shared templates, and predictable behavior across generators. It aligned internal tools, eliminated duplicated effort, and replaced trial-and-error debugging with reproducible builds. Every improvement in later versions built on this foundation.

Categorized improvements for v0.0.3

v0.0.4: Establishing the Foundation

v0.0.4 completed the core capabilities we need for production. With the moving parts aligned in v0.0.3, this release focused on the fundamentals. It added consistent warning governance, extraction controls that match established tools, schema support for IDE auto-completion, a complete reference system, and initial inline formatting in the generators. The bootstrap script became a one-step path to a working build. We also hardened the pipeline with modern CI practices—sanitizers, coverage integration, and standardized presets.

Categorized improvements for v0.0.4

v0.0.5: Stabilization and Public Readiness

v0.0.5 marked the transition toward a sustained development model and prepared the project for handoff. This release focused on presentation, polish, and reliability—ensuring that MrDocs was ready not only for internal use but for public visibility. During this period, we expanded the set of public demos, refined the website and documentation, and stabilized the infrastructure to support a growing user base. The goal was to leave the project in a state where it could continue evolving smoothly, with a stable core, clear development practices, and a professional public face.

Community and visibility: Beyond the commits, this release reflected broader activity around the project. We generated and published several new demos, many of which revealed integration issues that were subsequently fixed. As more external users began adopting MrDocs, the feedback loop accelerated: bug reports, feature requests, and real-world edge cases guided much of the work. New contributors joined the team, collaboration became more distributed, and visibility increased. Around the same time, I introduced MrDocs to developers at CppCon 2025, where it received strong feedback from library authors testing it on their own projects. The tool was beginning to gain recognition as a viable, modern alternative to Doxygen.

Technical progress: This release focused on correctness. We redesigned the documentation comment data structures to support recursive inline elements and render Markdown and HTML-style formatting correctly. We moved to non-nullable polymorphic types and optional references so that invariants fail at compile time rather than at runtime. User-facing updates included new sorting options, automatic compilation database detection, a quick reference index, broader namespace and overload grouping, and LLDB formatters for Clang and MrDocs symbols. We refreshed the website and documentation UI for accessibility and responsiveness, added new demos (including the MrDocs self-reference), and tightened CI with more sanitizers, stricter warning policies, and cross-platform bootstrap improvements.

Together, these improvements completed the transition from a developing prototype to a dependable product. v0.0.5 established a stable foundation for others to build on—polished, documented, and resilient—so future releases could focus on extending capabilities rather than consolidating them. With this release, the project reached a point where the handoff could occur naturally, closing one chapter and opening another.

Categorized improvements for v0.0.5

2026: Beyond the MVP

MrDocs now ships a working MVP, but significant foundational work remains. The priority framework is the same: start with gap analysis, shape an MVP (or now just a viable product), and rank follow-on work against that baseline. In 2025 we invested in presentation earlier than infrastructure. That inversion still raises costs: each foundational change forces rework across user-facing pieces.

I do not know how the leadership model will evolve in 2026. The team might keep a single coordinator or move to shared stewardship. Regardless, the project only succeeds if we continue investing in foundational capabilities. The steps below outline the recommendations I believe will help keep MrDocs sustainable over the long term.

Strategic Prioritization

Aligning priorities is itself the highest priority. At the start of my tenure as project lead we followed a strict sequence—gap analysis, then an MVP, then a set of priorities—but that model exposed limitations once work began to land. The issue tracker does not reflect how priorities relate to each other, and as individual tickets close the priority stack does not adjust automatically. The project’s complexity now amplifies the risk: without a clear view of dependencies we can assign a high-value engineer to a task that drags several teammates into the same bottleneck, resulting in net-negative progress. Defining priorities therefore includes understanding the team’s skills, mapping how they collaborate, and making sure no one becomes a sink that blocks everyone else. Alignment across roles remains essential so the plan reflects the people who actually execute it.

The tooling already exists to put this into practice. GitHub now lets us mark issues as blocked by or blocking others and to model parent/child relationships. We can use those relationships to reorganize the priorities programmatically. Once the relationships are encoded, priorities gain semantic meaning because we can explain why a small ticket matters in the larger story. Priorities become the byproduct of higher-level goals— narratives about the product—rather than a short-term static wish list of individual features.

We also need to strengthen the operational tools that keep the team coordinated. Coverage in CI is still far below our other C++ Alliance projects, and the gap shows up as crashes whenever a new library explores an untested path in the codebase. Improving coverage is a priority in its own right. We can pair that effort with automation and analysis tools like ReviewDog to accelerate code-review feedback, Danger.js to enforce pull-request policies, CodeClimate or similar services for static analysis, and clang-tidy checks to catch issues earlier. Finally, we can invite other collaborators to revisit the gap analysis and MVP, including C++Alliance colleagues who specialize in marketing. Their perspective will help us assign priorities that reflect both technical dependencies and the project’s broader positioning.

Reflection

The corpus keeps drifting out of sync because every important path in MrDocs duplicates representation by hand. Almost every subsystem reflects data from one format to another, and almost every internal operation traverses those structures. Each time we adjust a field we have to edit dozens of call sites, and even small mistakes create inconsistent state—different copies of the “truth” that evolve independently. Reflection eliminates this churn. If we can describe the corpus once and let the code iterate over those descriptions, the boilerplate disappears, the traversals remain correct, and we stop fighting the same battle.

A lightweight option would be to enforce the corpus from JSON the way we treat configuration, but the volume of metadata in AST makes that impractical. Instead, we lean on compile-time reflection utilities such as Boost.Describe and Boost.mp11. With those libraries we can convert the corpus to any representation, and each generator—including future binary or JSON targets—sees the same schema automatically. MrDocs can even emit the schema that powers each generator, keeping the schema, DOM, and documentation in sync. This approach also fixes the long-standing lag in the XML generator, where updates have historically been manual and error-prone.

Use cases: We can start by describing the Symbols, Javadoc, and related classes, shipping each refactor as a dedicated PR so reviews stay contained. Each description removes custom specializations, reverts to = default where possible, and replaces old logic with static asserts that enforce invariants. We generalize the main merge logic first, then update callers such as the AST visitor that walks RecordTranche, ensuring the Javadoc structure matches the new descriptions. A MRDOCS_DESCRIBE_DERIVED helper can enumerate derived classes so every visit routine becomes generic. Once the C++ side is described, we rebuild the lazy DOM objects on top of Describe so their types mirror the DOM layout directly.

Redundant non-member function like tag_invoke, operator⇔, toString, and merge collapse into shared implementations that use traits only when real customization is required. New generators—binary, JSON, or otherwise—drop in with minimal code because the schema and traversal logic already exist. The XML generator stops maintaining a private representation and simply reads the described elements. We can finally standardize naming conventions (kebab-case or camelCase) because the schema enforces them. Generating the Relax NG Compact file becomes just another output produced from the same description. A metadata walker can then discover auxiliary objects and emit DOM documentation automatically. As a side effect of integrating Boost.mp11, we can extend the tag_invoke context protocol with tuple-based helpers for mrdocs::FromValue, further narrowing the gap between concrete and DOM objects.

Metadata

MrDocs still carries metadata gaps that are too large to ignore. The subsections below highlight the three extraction areas that demand sustained effort; each of them blocks the rest of the system from staying consistent.

Recursive blocks and inlines. Release 0.0.5 introduced the data structures for recursive Javadoc elements, but we still do not parse those structures. The fix is straightforward in concept—extend the CommonMark-based parser so every block and inline variant becomes a first-class node—but the implementation is long because there are many element types. We can chip away incrementally by opening issues and sub-issues, tackling one structure per PR, and starting with block elements before moving to inlines. The existing parse_{rule} helpers already contain the mechanics; we just need to wire each rule into the new Javadoc nodes.

Legible names. The current name generator appends hash fragments to differentiate symbols lazily, which makes references unstable and awkward. We need a stable allocator that remembers which symbols claimed which names. The highest-priority symbol should receive the base name, and suffixes should cascade to less critical overloads so the visible entries stay predictable. Moving the generator into the extraction phase and storing the assignments there ensures anchors remain stable, lets us update artifacts such as the Boost.URL tagfile, and produces names that actually read well.

Populate expressions. Whenever the extractor fails to recognize an expression, it falls back to the raw source string. That shortcut prevents us from applying the usual transformations, especially inside requires-expressions where implementation-defined symbols appear. We should introduce typed representations for the constructs we already understand and continue to store strings for the expressions we have not modeled yet. As coverage grows, more expressions flow through the structured pipeline, and the remaining string-based nodes shrink to the truly unknown cases.

Extensions and Plugins

Extensions and plugins aim at the same outcome—letting projects customize MrDocs—but they operate at different layers. Extensions run inside the application, usually through interpreters we bundle. We already ship Lua and Duktape, yet today they only power a handful of Handlebars helpers. The plan is to widen that surface: add more interpreters where it makes sense, extend helper support so extensions can participate in escaping and formatting, and give extensions the ability to consume the entire corpus. With that access, an extension can list every symbol, emit metadata in formats we do not yet support, or transform the corpus before it reaches a native generator. The same mechanism enables quality-of-life utilities, such as a generator extension that checks whether a library’s public API changed according to a policy defined in code.

Plugins, by contrast, are compiled artifacts. They unlock similar customization goals, but their ABI must stay stable, and platform differences mean a plugin built on one system will not run on another. To keep the surface manageable we should expose a narrow wrapper: pass plugins a set of DOM proxies so they never depend on the underlying Info classes, use traits or versioned interfaces to handle incompatibilities, and plan the API carefully before release. Python remains a middle path that bridges both approaches. By documenting a Python extension layer, we provide interpreted helpers that are easy to write, support Handlebars customization, and give teams a quick way to automate workflows before they invest in a compiled plugin.

Dependency Resilience

Working with dependent libraries is still the most fragile part of the MrDocs workflow. Environments drift, transitive dependencies change without notice, and heavyweight projects force us to install toolchains we do not actually need. In Boost.URL alone we watch upstream Boost libraries evolve every few weeks; sometimes the code truly breaks, but just as often a new release exercises an untested path in MrDocs and triggers a crash because our coverage is still thin. Other ecosystems push the cost even higher: documenting a library that depends on LLVM can turn a three-second render into an hours-long process because the headers are generated at build time, so we must compile and install LLVM merely to obtain include files. CI environments regularly fail for the same reason.

We already experimented with mitigation strategies and should refine them rather than abandon the ideas. Shipping a curated standard library with MrDocs removes one entire category of instability. The option will soon be disabled by default, but users can still enable it or even combine it with the system library when reproducibility matters more than absolute fidelity. This mirrors how Clang ships libc++; it does not allow invalid code, it simply guarantees a known baseline.

On top of that, we have preliminary support for user-defined stubs. Configuration files can provide short descriptions of expected symbols from hard-to-build dependencies, and MrDocs can inject those during extraction. For predictable patterns we can auto-generate stubs when the user opts in, synthesizing symbols rather than failing immediately. None of this accepts invalid code—the compiler still diagnoses real errors—but it shields projects from breakage when a transitive dependency tweaks implementation details or when generated headers are unavailable. The features remain optional, so teams can disable synthesis to debug the underlying issue and still benefit from the faster path when schedules are tight. Even if the project moves in another direction we should document the proposal and remove the existing stub hooks deliberately rather than letting them linger undocumented.

The payoffs are clear. Boost libraries could generate documentation without cloning the entire super-project, relying on SettingsDB to produce a compilation database and skipping CMake entirely. MrDocs itself could publish reference docs without building LLVM because the required symbols would come from curated stubs. Release engineering would stop grinding to a halt every time a transitive dependency changes, and developers would regain hours currently spent firefighting. These are the stability and reproducibility gains we need if we want MrDocs to be the default tooling for large C++ ecosystems.

Follow-up Issues for v0.0.6

To keep this post focused on the big-picture transition, I spun the tactical tasks into GitHub issues for the 0.0.6 milestone. They’re queued up and ready for execution whenever the team circles back to implementation.

List of follow-up issues for v0.0.6
  • #1081 Support custom stylesheets in the HTML generator
  • #1082 Format-agnostic Handlebars generator extension
  • #1083 Allow SettingsDB to describe a single source file
  • #1084 Guard against invalid source links
  • #1085 Complete tests for all using declaration forms
  • #1086 Explore a recursive project layout
  • #1087 Convert ConfigOptions.json into a schema file
  • #1088 Separate parent context and parent page
  • #1089 List deduction guides on the record page
  • #1090 Expand coverage for Friends
  • #1091 Remove dependency symbols after finalization
  • #1092 Review Bash Commands Parser
  • #1093 Review NameInfoVisitor
  • #1094 Improve overload-set documentation
  • #1095 CI uses the bootstrap script
  • #1096 Connect Antora extensions
  • #1097 Handlebars: optimize render state
  • #1098 Handlebars: explore template compilation
  • #1099 Handlebars: investigate incremental rendering

Acknowledgments

Matheus Izvekov and Krystian Stasiowski kept the Clang integration moving. Their expertise cleared issues that would have stalled us. Gennaro Prota and Fernando Pelliccioni handled the maintenance load that kept the project on schedule. They took on the long tasks and followed them through.

Robert Beeston and Julio Estrada delivered the public face of MrDocs. The site we ship today exists because they turned open-ended goals into a complete experience.

Vinnie Falco, Louis Tatta, and Sam Darwin formed the backbone of my daily support. Vinnie trusted the direction and backed the plan when decisions were difficult. Louis made sure I had space to return after setbacks. Sam kept the Alliance infrastructure running so the team always had what it needed.

Ruben Perez, Klemens Morgenstern, Peter Dimov, and Peter Turcan offered candid feedback whenever we needed another perspective. Their observations sharpened the product and kept collaboration positive.

Joaquín M López Muñoz and Arnaud Bachelier guided me through the people side of leadership. Their advice turned complex situations into workable plans.

Working alongside everyone listed here has been a privilege. Their contributions made this year possible.

Conclusion

The 2025 releases unified the generators, locked the configuration model, added sanitizers and coverage to CI, and introduced features that make the tool usable outside Boost.URL. The project is ready for new contributors because they can extend the code without rebuilding the basics, and downstream teams can run the CLI on large codebases and expect predictable output.

While we delivered those releases, I learned that engineering progress depends on steady communication. Remote discussions often sound negative even when people agree on the goals, so I schedule short check-ins, add light signals like emojis, and keep space for conversations that are not task-driven. I also protect time to listen and ask for help when the workload gets heavy; if I lose that time, every deadline slips anyway.

Final Reflections

  • Technical conversations start negative by default, so add clear signals when you agree or appreciate the work.
  • Assume terse feedback comes from the medium, not the person, and respond with patience.
  • Keep informal connection habits—buddy calls, breaks, or quick chats—to maintain trust.
  • Look after your own health and use outside support when needed.
  • Never allow the schedule to block real listening time; reset your calendar when that happens.

All Posts by This Author