Error message from scribble/example is missing some information
Nobody has claimed this yet.
- Dominant language
- Racket
- Stars
- 250
- Forks
- 102
- Avg merge
- 11d 11h
- Merged PRs (30d)
- 1
Description
Given this Scribble document:
#lang scribble/manual
@(require scribble/example)
@(examples #:eval (make-base-eval) (+ 1 2 'bang!))
And this info.rkt file:
#lang info
(define collection "examples-test")
(define scribblings
'(("examples-test.scrbl" (multi-page) (library) "examples-test")))
Installing the package and subsequent runs of raco setup results in this (expected) error being raised:
error: during building docs for <pkgs>/examples-test/examples-test.scrbl
examples: exception raised in example
error: "+: contract violation\n expected: number?\n given: 'bang!\n argument position: 3rd\n other arguments...:\n 1\n 2"
context...:
.../scribble/eval.rkt:308:23: with-handlers-handler107
.../racket/private/more-scheme.rkt:163:2: select-handler/no-breaks
.../scribble/eval.rkt:339:9
.../scribble/eval.rkt:761:0: do-titled-interaction
.../examples-test/examples-test.scrbl: [running body]
.../setup/scribble.rkt:901:0: load-doc/ensure-prefix
.../setup/scribble.rkt:1159:13
.../parallel-do.rkt:390:17
.../racket/private/more-scheme.rkt:261:28
.../setup/parallel-do.rkt:435:20: loop
This error message is hard to parse and could use some more information. Additionally, the module that is shown in the "during build docs" message is not always where the example is located. If a document module uses include-section on a module with examples that throw an exception, the "building docs for" message uses the including module, not the included module. The module that actually contained the evaluation failure is included in context as the [running body] entry, but that's in the middle of a dozen other modules and it's easy to miss. The following changes could make this message more helpful:
- Either omit the
contextentries before the[running body]module or put the module that contained the example somewhere more noticeable. Maybe changingexamples: exception raised in exampletopath/to/examples-test.scrbl: examples: exception raised in examplewould work. - If the string contained in
error:is formatted according to Racket's error message conventions, don't display it as a quoted string and instead display it in a nested manner like this:
error: +: contract violation
expected: number?
given: 'bang!
argument position: 3rd
other arguments...:
1
2
context: ...
- Include the example expression that raised the error as
example: (+ 1 2 'bang!). - Rename
error:toexception:because that's what it's called in theexamples: exception raised in examplemessage.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with scribble/eval.rkt around the handlers shown in the context and reproduce the failure using the examples-test.scrbl document with raco setup. Trace how include-section affects the reported module and how the exception text is formatted; done means the failing example, its containing module, and the exception details are presented clearly without requiring the reader to search the context.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100