Skip to content

Compile: report a clear error when the readme block contains */ #1020

Description

@mazany

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions