Skip to content

Autodoc: improve error reporting #22902

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Feb 22, 2025

Conversation

ianprime0509
Copy link
Contributor

@ianprime0509 ianprime0509 commented Feb 15, 2025

This PR aims to improve error handling and reporting in Autodoc, to help address potentially confusing scenarios such as the one described here: https://ziggit.dev/t/file-has-unexpected-syntax-error-when-building-documentation/8387

There are several changes included:

  • Any parse errors in source files are reported to the user, and the AST is replaced with that of an empty file to avoid the rest of Autodoc bugging out when trying to handle an incomplete/invalid AST.
  • The "file must contain trailing newline" check is converted from an assertion to a reported and handled error.
  • The JS log function is enhanced to accept the log level so it can use console.error, console.warn, etc. instead of console.log (this brings several benefits, including colors in the browser console and stack traces for error logs).
  • The panic handling is unified and implemented in the Zig Wasm code, using the error logging.
  • Any errors (including panics) are reported to the user in the UI, checking off one item of autodoc follow-up enhancements and bug fixes #19249.
    • Edit: actually, I just noticed this PR checks two items off that issue:
      • "make the panic handler reflect the failure in the user interface"
      • "instead of logging "can't index foo because it has syntax errors" put it in the UI"

Screenshots of Autodoc with the following simple project:

s.zig
fdsafdsaf fdsafd dfdafa
g.zig
//! Implementation of playing card ranks

/// This is a rank
pub const Rank = enum {
    Nine,
};

(no newline at end of file)

light mode view

dark mode view

Additionally, this commit streamlines the way unparseable files are handled, by giving them the AST of an empty file. This avoids bugs in the rest of the Autodoc logic trying to work with invalid ASTs.

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
Using the browser's `console.error`, etc. functions instead of `console.log` produces prettier output in the console. Additionally, `console.error` in particular includes a stack trace, which is useful for debugging where the error occurred.

Additionally, this commit leverages the enhanced logging to delete the separate `panic` function from the JS code and write it in Zig instead.
Also includes panics by virtue of the previous commit, checking one item off ziglang#19249.
@andrewrk
Copy link
Member

Very nice!

@andrewrk andrewrk merged commit 0dcba03 into ziglang:master Feb 22, 2025
9 checks passed
@ianprime0509 ianprime0509 deleted the autodoc-error-reporting branch February 22, 2025 22:21
@achan1989 achan1989 mentioned this pull request May 4, 2025
5 tasks
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.

None yet

2 participants