Skip to content

Fix comment handling when looking for commands - #507

Merged
davidlattimore merged 1 commit into
evcxr:mainfrom
MaxFreedomPollard:fix-comment-handling-before-commands
Sep 7, 2026
Merged

davidlattimore merged 1 commit into
evcxr:mainfrom
MaxFreedomPollard:fix-comment-handling-before-commands

Conversation

@MaxFreedomPollard

Copy link
Copy Markdown
Contributor

Comment lines are only skipped while evcxr looks for commands if they start at column zero, so an indented comment before a command ends the search and the command is then treated as Rust code. ctx.check(" // An indented comment\n :an_invalid_command") reports a syntax error at the colon instead of "Unrecognised command", and the same input through execute fails to compile rather than running the command.

The check in evcxr/src/code_block.rs is also too broad in the other direction. line.starts_with("//") matches /// too, so a doc comment at column zero is skipped and never reaches the compiler, and the item it documents ends up with no documentation. check_for_doc only passes because its ///this is my struct happens to be indented; put it at column zero and :doc MyStruct prints the struct with the doc text gone.

from_original_user_code now trims leading whitespace before it looks for //, and an outer doc comment no longer ends the search on its own. It is held as the point where the code starts if code follows it, and dropped if a command follows, which is what happened before. //! and //// stay plain comments: an inner doc comment would document the module evcxr generates around the cell rather than any of the user's code, and //// is not a doc comment to rustc either.

Tests:

  • cargo test -p evcxr -- --test-threads 1, on macOS with rustc 1.98.0: 32 unit tests and 48 integration tests pass.
  • The four new unit tests and the two new integration tests fail on main. indented_comment_before_command finds no commands, doc_comment_stays_with_its_item loses the /// line, command_after_indented_comment gets error 2:5-2:6 instead of error 2:1-2:20, and check_for_doc_starting_at_column_zero gets ctx\n\nstruct MyStruct(usize) with the doc text missing. doc_comment_before_command_is_dropped and comments_that_arent_outer_doc_comments_are_dropped pin behaviour that has not changed and pass either way.
  • cargo fmt --all -- --check
  • cargo clippy -p evcxr --all-targets

No new dependencies, so Cargo.lock and cackle.toml are untouched.

Comment lines were only skipped while evcxr looked for commands if they started
at column zero, so an indented comment before a command ended the search and the
command was then treated as Rust code. Checking
"    // An indented comment\n    :an_invalid_command" reported a syntax error at
the colon rather than "Unrecognised command".

The same check was too broad in the other direction: line.starts_with("//") also
matches "///", so a doc comment at column zero was skipped and never reached the
compiler, leaving the item it documented with no documentation. check_for_doc
only passes because its "///this is my struct" is indented.

from_original_user_code now trims leading whitespace before looking for "//", and
an outer doc comment no longer ends the search on its own. It is held as the
point where the code starts if code follows it, and dropped if a command follows,
which is what happened before. "//!" and "////" stay plain comments: an inner doc
comment would document the module that evcxr generates around the cell, and
"////" is not a doc comment to rustc either.
@davidlattimore

Copy link
Copy Markdown
Collaborator

Thanks :)

@davidlattimore
davidlattimore merged commit 2d2de8f into evcxr:main Sep 7, 2026
5 checks passed
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.

2 participants