Skip to content

docs: fix exception-handling examples and Lua.new option doctests#387

Merged
davydog187 merged 2 commits into
mainfrom
docs/fix-exception-examples
Jul 15, 2026
Merged

docs: fix exception-handling examples and Lua.new option doctests#387
davydog187 merged 2 commits into
mainfrom
docs/fix-exception-examples

Conversation

@davydog187

Copy link
Copy Markdown
Contributor

What

Fixes three classes of documentation mistake around exception handling and doctest rendering. All examples were verified by running them.

1. README: e.message returns nil

The "Error messages with source and line" tour rescued a Lua.RuntimeException from error("...") and read e.message. Since #384, that field is nil when the exception wraps a VM error — the message is rendered lazily via Exception.message/1. Switched the example to the accessor.

The illustrative comment was also wrong: it showed a Runtime Error title line the formatter never emits. Corrected to the actual (ANSI-elided) frame:

Lua runtime error: at <eval>:2:

  runtime error: something went wrong

e.line/e.source were already correct and are unchanged.

2. Lua.new/1 option doctests rendered as plain text

The three ## Options doctests (:max_call_depth, :max_string_bytes, :max_instructions) were indented 6 spaces. Nested under 2-space bullets, a code block needs 8 spaces — so Markdown/ExDoc rendered them as lazy continuation paragraphs instead of highlighted code blocks. Re-indented all three (confirmed via mix docs that each now renders inside a <pre> block within its bullet).

Also replaced the double-escaped \"x\" in the :max_string_bytes example with a single-quoted Lua string ('x') so it renders cleanly.

3. Marketing snippets used a function that doesn't exist

website/.../snippets.ex called Lua.eval/2 (only Lua.eval!/2 exists) in three places, and the sandbox snippet read the nil .message field with the wrong expected substring. Rewrote to idiomatic Lua.eval!/2 (correct {results, lua} shape; the sandbox one now shows the raise, matching os.execute(_) is sandboxed).

Verification

  • mix test --only doctest — 49 pass (the three re-indented Lua.new/1 doctests included).
  • mix docs — the three option examples now render as code blocks; \"x\" escaping gone.
  • mix format --check-formatted lib/lua.ex — clean.
  • Website compiles.

The README error-handling tour read `e.message`, but the wrapper leaves
that field nil when it wraps a VM exception (since #384); the message is
rendered lazily via `Exception.message/1`. Switch the example to the
accessor and correct the illustrative frame — the formatter emits
location-then-body, with no "Runtime Error" title line.

Re-indent the three Lua.new/1 `## Options` doctests from 6 to 8 spaces so
ExDoc renders them as code blocks inside the bullet list rather than plain
continuation paragraphs, and drop the double-escaped \"x\" in favour of a
single-quoted Lua string so it renders cleanly.

Fix the marketing snippets: `Lua.eval/2` does not exist (only eval!/2), and
the sandbox snippet read the nil `.message` field with the wrong expected
text.
Comment thread README.md Outdated
@davydog187 davydog187 merged commit 47a8aec into main Jul 15, 2026
5 checks passed
@davydog187 davydog187 deleted the docs/fix-exception-examples branch July 15, 2026 14:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant