Summary
A mod's readme lives inside a C block comment. If the markdown contains a
literal */, the comment closes early, the rest of the readme is parsed as
C++, and the resulting errors point somewhere else entirely. A targeted check —
"readme block contains a comment terminator at line N" — would turn a
mystifying failure into a one-line fix.
Why
The readme is markdown, and markdown in a mod's readme routinely contains code.
Any example that shows a CSS or C comment ends with */. So the trap is not
exotic: it is what happens the first time an author documents the very syntax
their mod reads.
The failure is unusually hard to read because the errors surface in a different
file. Nothing in the output points at the readme.
Evidence
Documenting a metadata header my mod parses out of CSS files, I wrote this in
the readme block:
/* ==Patch==
@name Darker surface
@theme dark
==/Patch== */
The */ on the last line closed ==WindhawkModReadme=='s enclosing comment.
Compilation then failed like this (2.0.0-alpha.2, mod install --file):
electron-css-inject.wh.cpp:74:5: warning: '/*' within block comment [-Wcomment]
electron-css-inject.wh.cpp:79:1: error: expected unqualified-id
79 | `@theme dark` or `@theme light` means the patch is only injected under that
electron-css-inject.wh.cpp:104:1: error: unknown type name 'with'
...
C:/Program Files/Windhawk/Compiler/include/windhawk_utils.h:381:9: error: use of undeclared identifier 'RemoveWindowSubclass'
C:/Program Files/Windhawk/Compiler/include/windhawk_utils.h:394:5: error: unknown type name 'SUBCLASSPROC'
...
4 warnings and 10 errors generated.
Ten errors, six of them inside windhawk_utils.h — a file I had not touched
and which is not the problem. The -Wcomment warning is the only real clue and
it is buried above errors that look far more serious. The obvious first theory
is a broken toolchain or a header incompatibility, which is a long way from the
truth.
Suggested shape
When splitting the source into metadata / readme / settings / code, scan the
readme block for */ and fail early:
error: readme block contains a comment terminator (*/) at line 76;
it would close the enclosing comment. Escape it or reword the example.
The same check is worth applying to the settings block for the same reason.
Alternatives considered
- Let authors escape it. Needs a documented escape nobody will discover
until after they've hit the bug — which is the bug.
- A different readme delimiter (fenced sentinel lines rather than a C
comment) would remove the class of problem entirely, but that is a breaking
format change for every existing mod. The diagnostic gets most of the value
for a fraction of the cost and risk.
Tested on 2.0.0-alpha.2.
Summary
A mod's readme lives inside a C block comment. If the markdown contains a
literal
*/, the comment closes early, the rest of the readme is parsed asC++, and the resulting errors point somewhere else entirely. A targeted check —
"readme block contains a comment terminator at line N" — would turn a
mystifying failure into a one-line fix.
Why
The readme is markdown, and markdown in a mod's readme routinely contains code.
Any example that shows a CSS or C comment ends with
*/. So the trap is notexotic: it is what happens the first time an author documents the very syntax
their mod reads.
The failure is unusually hard to read because the errors surface in a different
file. Nothing in the output points at the readme.
Evidence
Documenting a metadata header my mod parses out of CSS files, I wrote this in
the readme block:
The
*/on the last line closed==WindhawkModReadme=='s enclosing comment.Compilation then failed like this (2.0.0-alpha.2,
mod install --file):Ten errors, six of them inside
windhawk_utils.h— a file I had not touchedand which is not the problem. The
-Wcommentwarning is the only real clue andit is buried above errors that look far more serious. The obvious first theory
is a broken toolchain or a header incompatibility, which is a long way from the
truth.
Suggested shape
When splitting the source into metadata / readme / settings / code, scan the
readme block for
*/and fail early:The same check is worth applying to the settings block for the same reason.
Alternatives considered
until after they've hit the bug — which is the bug.
comment) would remove the class of problem entirely, but that is a breaking
format change for every existing mod. The diagnostic gets most of the value
for a fraction of the cost and risk.
Tested on 2.0.0-alpha.2.