leanprover-community / leanprover-community/lean

Bug in docstring code block error detection

Open
#108 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
C++
Stars
434
Forks
79
PR merge metrics
No merged PRs in 30d

Description

edit: I did the tests below in 3.4.2, the behavior in 3.5.1 is detailed in the following comment.

I think the following is an accurate description of the current state of affairs: inside a docstring, adding a language tag to a code block surrounded by triple-backticks leads to an error if there's any non-whitespace text after the final code block.

A few examples:

No error:

/-!
```lean
code
```
-/

This gives the error invalid doc string, end of code block ``` expected (but it shouldn't):

/-!
```lean
code
```
non-whitespace text afterwards
-/

This gives no error:

/-!
```
code
```
non-whitespace text afterwards
-/

This example also gives no error. Compare this example in mathlib's reassoc_tactic) (pointed out by @robertylewis):

/-!
```lean
code
```
non-whitespace text afterwards
```
more code
```
-/

This gives an error (but it shouldn't):

/-!
```lean
code
```
non-whitespace text afterwards
```
more code
```
more non-whitespace text
-/

Lean thinks this is OK, but it isn't:

/-!
```lean
code
```
non-whitespace text afterwards
```
-/

The error message comes from src/library/documentation.cpp.

Originally reported by @jcommelin on zulip.

Contributor guide

Open the contributing guide

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 in src/library/documentation.cpp at the error reported around line 160, then reproduce the tagged and untagged code-block examples from the issue. Done means docstrings with a language-tagged triple-backtick block accept trailing non-whitespace text consistently with the examples and no longer emit the incorrect end-of-code-block error.

Written by the indexing model from the issue text.

Assessment

Tech stack
cpp
Domain
documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.