Workflow & PR hygiene

Coding Standards

Paths

The AST visitor and metadata all use forward slashes to represent file pathnames, even on Windows. This is so the generated reference documentation does not vary based on the platform.

Exceptions

Errors thrown by the program should always have type Exception. Objects of this type are capable of transporting an Error object. This is important for the scripting to work; exceptions are used to propagate errors from library code to scripts and back to the invoking code. For exceptional cases, these thrown exceptions should be uncaught. The tool installs an uncaught exception handler that prints a stack trace and exits the process immediately.

Style Guide

This project follows informal formatting conventions established by previous Boost projects. To help contributors, we provide a .clang-format file that encodes these rules.

  • Do not apply clang-format across entire files or the whole project.

  • Use the config only as a reference for your IDE/editor, or to format the code you personally add or modify in a commit.

  • Always check the surrounding code and keep consistent with it.

  • Do not create style-only commits that introduce large diffs without functional changes.

Why This Approach:

  • Keeps history clean: avoids large, style-only commits.

  • Ensures new contributors are not lost when adapting to project style.

  • Encourages consistency without rigid automation.

General Advice: When in doubt, copy the style of the surrounding code. The .clang-format file is a tool to help you, not a rule to enforce blindly.

The utility script ./util/reformat.sh can also be used to check a few project invariants, such as header guards and include order.

Contributing

If you find a bug or have a feature request, please open an issue on the MrDocs GitHub repository: https://github.com/cppalliance/mrdocs/issues

If you would like to contribute a feature or bug fix, please open a pull request on the MrDocs GitHub repository: https://github.com/cppalliance/mrdocs/pulls

If you would like to discuss a feature or bug fix before opening a pull request, discussing happen in the #mrdocs channel on the Cpplang Slack: https://cpplang.slack.com/