No @return on any of the five tooling interface functions, so the pointer encoding is documented nowhere the compiler carries

[thedavidmeister]

Audit scope: whole-repo, commit 7aa85a4

Recovered from the interface reviewer's report (its finding F6); dimension 3 (documentation), severity low.

Where

src/interface/IIntegrityToolingV1.sol:19; src/interface/IOpcodeToolingV1.sol:18; src/interface/IParserToolingV1.sol:18,28; src/interface/ISubParserToolingV1.sol:17

Problem

All five builders return bytes memory and none documents it. The encoding — two bytes per function pointer, positionally indexed — is the entire contract of these functions, and it is stated nowhere the compiler can carry into a consumer's artifact.

Measured

nix develop -c forge inspect src/interface/IIntegrityToolingV1.sol:IIntegrityToolingV1 devdoc returns {"version":1,"kind":"dev","title":"…"} with no methods key at all — the devdoc for these interfaces carries no per-function documentation.

This is also an in-repo inconsistency: src/lib/LibCodeGen.sol documents @return on every function. And the concrete encoding facts already exist in this repo, in the comment strings LibCodeGen emits into the generated file — "/// @dev Every two bytes is a function pointer for a literal parser." at src/lib/LibCodeGen.sol:151, with equivalents at :126-129, :177-179, :201-205. The interfaces just do not repeat them.

Proposed fix

Add a @return to each declaration, carrying the encoding the library already documents:

--- a/src/interface/IParserToolingV1.sol
+++ b/src/interface/IParserToolingV1.sol
     /// .github/workflows/build-pointers.yaml for an example of such a test.
+    /// @return Every two bytes is a function pointer for an operand handler,
+    /// positionally indexed to match the parse meta.
     function buildOperandHandlerFunctionPointers() external pure returns (bytes memory);
...
+    /// @return Every two bytes is a function pointer for a literal parser,
+    /// dispatched on the first byte(s) of the literal.
     function buildLiteralParserFunctionPointers() external pure returns (bytes memory);

with equivalents for buildOpcodeFunctionPointers, buildSubParserWordParsers and buildIntegrityFunctionPointers.