Workflow & PR hygiene

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.

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.

A plugin is compiled against the public headers and loaded into the running tool, so it sees C++ types by their layout rather than through an insulating boundary. MRDOCS_PLUGIN_API_VERSION is what turns a mismatch into a diagnostic instead of a crash: Mr.Docs refuses to call a plugin that reports a different value, and the plugin’s copy of the value comes from the headers it was compiled against.

Raise it in the same commit that changes what a plugin sees. That is wider than the plugin header: it takes in the Generator and Transform interfaces and every public type a plugin can hold or be handed, so a new member in a symbol type counts, while a change confined to src/ does not. When in doubt, raise it. The cost of raising it is that plugin authors rebuild; the cost of not raising it is a crash in someone else’s process.