bug(`forge doc`): fails to parse Solidity code, "unrecognized token 'layout', expected identifier"

[alvrs]

Component

Forge

Have you ensured that all of these are up to date?

• Foundry
• Foundryup

What version of Foundry are you on?

forge Version: 1.2.1-stable Commit SHA: 42341d5 Build Timestamp: 2025-05-26T05:24:44.498129000Z (1748237084) Build Profile: maxperf

What version of Foundryup are you on?

foundryup: 1.0.1

What command(s) is the bug in?

forge doc --build

Operating System

macOS (Apple Silicon)

Describe the bug

Encountering an issue with forge doc --build failing to parse Solidity that includes layout in a comment and as parameter name when upgrading to nightly or 1.2.1. It was working on v1.1.0.

Line that is causing the error: https://github.com/latticexyz/mud/blob/d2c77c206d94a00082a25939b786df04d8249fcb/packages/store/src/StoreSwitch.sol#L37

More details in this failing action: https://github.com/latticexyz/mud/actions/runs/15298781272/job/43034047184?pr=3719

Related PR: latticexyz/mud#3719

Full error message

``` Error: Failed to parse Solidity code for /Users/alvarius/git/latticexyz/mud/packages/store/src/StoreSwitch.sol Debug info: [Diagnostic { loc: File(31, 1475, 1481), level: Error, ty: ParserError, message: "unrecognised token 'layout', expected identifier, \")\", \",\", \"revert\", \"at\", \"leave\", \"switch\", \"case\", \"def ault\"", notes: [] }, Diagnostic { loc: File(31, 1481, 1482), level: Error, ty: ParserError, message: "unrecognised token ')', expected \"at\"", notes: [] }, Diagnostic { loc: File(31, 1522, 1530), level: Error, ty: ParserError, message: "unrecognised token 'assembly', expected identifier, annotation, string, hexstring, address, number, rational, hexnumber, \";\", \"}\", \"(\", \"[\", Uint, Int, Bytes, \"byte\", \"struct\", \"bo ol\", \"address\", \"string\", \"bytes\", \"event\", \"enum\", \"type\", \"true\", \"false\", \"payable\", \"constructor\", \"function\", \"mapping\", \"receive\", \"fallback\", \"at\", \"using\", \"modifier\", \"lea ve\", \"switch\", \"case\", \"default\"", notes: [] }, Diagnostic { loc: File(31, 1539, 1545), level: Error, ty: ParserError, message: "unrecognised token 'layout', expected identifier, annotation, string, hexstring, address, number, rational, hexnumber, \";\", \"}\", \"(\", \"[\", Uint, Int, Bytes, \"byte\", \"struct\", \"bool\", \"address\", \"string\", \"bytes\", \"event\", \"enum\", \"type\", \"true\", \"false\", \"payable\" , \"constructor\", \"function\", \"mapping\", \"receive\", \"fallback\", \"at\", \"using\", \"modifier\", \"leave\", \"switch\", \"case\", \"default\"", notes: [] }, Diagnostic { loc: File(31, 1545, 1546), level: Err or, ty: ParserError, message: "unrecognised token '.', expected \"at\"", notes: [] }, Diagnostic { loc: File(31, 1953, 1955), level: Error, ty: ParserError, message: "unrecognised token 'if', expected identifier, ann otation, string, hexstring, address, number, rational, hexnumber, \";\", \"}\", \"(\", \"[\", Uint, Int, Bytes, \"byte\", \"struct\", \"bool\", \"address\", \"string\", \"bytes\", \"event\", \"enum\", \"type\", \"tru e\", \"false\", \"payable\", \"constructor\", \"function\", \"mapping\", \"receive\", \"fallback\", \"at\", \"using\", \"modifier\", \"leave\", \"switch\", \"case\", \"default\"", notes: [] }, Diagnostic { loc: File( 31, 1971, 1973), level: Error, ty: ParserError, message: "unrecognised token '==', expected identifier, \")\", \"++\", \"--\", \"[\", \".\", \",\", \"revert\", \"at\", \"leave\", \"switch\", \"case\", \"default\"", n otes: [] }, Diagnostic { loc: File(31, 1983, 1984), level: Error, ty: ParserError, message: "unrecognised token ')', expected \"++\", \"--\", \"[\", \".\"", notes: [] }, Diagnostic { loc: File(31, 1994, 2000), level: Error, ty: ParserError, message: "unrecognised token 'return', expected identifier, annotation, string, hexstring, address, number, rational, hexnumber, \";\", \"}\", \"(\", \"[\", Uint, Int, Bytes, \"byte\", \"stru ct\", \"bool\", \"address\", \"string\", \"bytes\", \"event\", \"enum\", \"type\", \"true\", \"false\", \"payable\", \"constructor\", \"function\", \"mapping\", \"receive\", \"fallback\", \"at\", \"using\", \"modifie r\", \"leave\", \"switch\", \"case\", \"default\"", notes: [] }, Diagnostic { loc: File(31, 2032, 2038), level: Error, ty: ParserError, message: "unrecognised token 'return', expected identifier, annotation, string, hexstring, address, number, rational, hexnumber, \";\", \"}\", \"(\", \"[\", Uint, Int, Bytes, \"byte\", \"struct\", \"bool\", \"address\", \"string\", \"bytes\", \"event\", \"enum\", \"type\", \"true\", \"false\", \ "payable\", \"constructor\", \"function\", \"mapping\", \"receive\", \"fallback\", \"at\", \"using\", \"modifier\", \"leave\", \"switch\", \"case\", \"default\"", notes: [] }, Diagnostic { loc: File(31, 2397, 2398), level: Error, ty: ParserError, message: "unrecognised token '=', expected identifier, \"{\", \"(\", \"++\", \"--\", \"[\", \".\", \"memory\", \"calldata\", \"storage\", \"transient\", \"public\", \"private\", \"exter nal\", \"internal\", \"constant\", \"revert\", \"at\", \"override\", \"immutable\", \"leave\", \"switch\", \"case\", \"default\"", notes: [] }, Diagnostic { loc: File(31, 22533, 22534), level: Error, ty: ParserError, message: "unrecognised token '}', expected identifier, annotation, string, hexstring, address, number, rational, hexnumber, \";\", \"(\", \"[\", Uint, Int, Bytes, \"byte\", \"struct\", \"import\", \"contract\", \"pr agma\", \"bool\", \"address\", \"string\", \"bytes\", \"interface\", \"library\", \"event\", \"enum\", \"type\", \"true\", \"false\", \"payable\", \"function\", \"mapping\", \"at\", \"abstract\", \"using\", \"leave\" , \"switch\", \"case\", \"default\"", notes: [] }] ```

[zerosnacks]

Likely related to an edge case in #10509

cc @DaniPopes

[DaniPopes]

Same as #10556