racket / racket/scribble

Error message from scribble/example is missing some information

Open
#141 0 comments 0 reactions 0 assignees View on GitHub

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 context entries before the [running body] module or put the module that contained the example somewhere more noticeable. Maybe changing examples: exception raised in example to path/to/examples-test.scrbl: examples: exception raised in example would 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: to exception: because that's what it's called in the examples: exception raised in example message.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.