Skip to content

[rustdoc] Give more information into extracted doctest information #141399

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

Open
wants to merge 5 commits into
base: master
Choose a base branch
from

Conversation

GuillaumeGomez
Copy link
Member

@GuillaumeGomez GuillaumeGomez commented May 22, 2025

Follow-up of #134531.

This update fragment the doctest code into its sub-parts to give more control to the end users on how they want to use it.

The new JSON looks like this:

{
  "format_version":2,
  "doctests":[
    {
      "file":"$DIR/extract-doctests-result.rs",
      "line":8,
      "doctest_attributes":{
        "original":"",
        "should_panic":false,
        "no_run":false,
        "ignore":"None",
        "rust":true,
        "test_harness":false,
        "compile_fail":false,
        "standalone_crate":false,
        "error_codes":[],
        "edition":null,
        "added_css_classes":[],
        "unknown":[]
      },
      "original_code":"let x = 12;\nOk(())",
      "doctest_code":{
        "crate_level":"#![allow(unused)]\n",
        "code":"let x = 12;\nOk(())",
        "wrapper":{
          "before":"fn main() { fn _inner() -> core::result::Result<(), impl core::fmt::Debug> {\n",
          "after":"\n} _inner().unwrap() }",
          "returns_result":true
        }
      },
      "name":"$DIR/extract-doctests-result.rs - (line 8)"
    }
  ]
}

for this doctest:

let x = 12;
Ok(())

With this, I think it matches what you need @ojeda? If so, once merged I'll update the patch I sent to RfL.

r? @aDotInTheVoid

@rustbot rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. T-rustdoc-frontend Relevant to the rustdoc-frontend team, which will review and decide on the web UI/UX output. labels May 22, 2025
@GuillaumeGomez GuillaumeGomez changed the title Extracted doctest [rustdoc] Give more information into extracted doctest information May 22, 2025
@rust-log-analyzer

This comment has been minimized.

@GuillaumeGomez
Copy link
Member Author

Fixed fmt.

Copy link
Contributor

@lolbinarycat lolbinarycat left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Core logic looks correct (mostly just exposing existing variables), just have a few nits about naming to hopefully increase readability.

@GuillaumeGomez
Copy link
Member Author

Updated.

Copy link
Contributor

@lolbinarycat lolbinarycat left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks pretty good, I've just got a few more notes about naming, most of which are extrapolations of previous suggested changes.

Copy link
Member

@aDotInTheVoid aDotInTheVoid left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This also needs changes to the docs for this feature, which are in the rustdoc book.

@rustbot rustbot added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels May 26, 2025
@rust-log-analyzer

This comment has been minimized.

@GuillaumeGomez
Copy link
Member Author

Applied suggestions!

Copy link
Contributor

@lolbinarycat lolbinarycat left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think we should be putting the test stdout directly into the docs, at least not unmodified

@GuillaumeGomez
Copy link
Member Author

I fixed the book example.

@rustbot rustbot added O-unix Operating system: Unix-like O-windows Operating system: Windows labels Jun 5, 2025
@rustbot
Copy link
Collaborator

rustbot commented Jun 5, 2025

The Miri subtree was changed

cc @rust-lang/miri

Some changes occurred to the intrinsics. Make sure the CTFE / Miri interpreter
gets adapted for the changes, if necessary.

cc @rust-lang/miri, @RalfJung, @oli-obk, @lcnr

Some changes occurred in src/tools/clippy

cc @rust-lang/clippy

@oli-obk
Copy link
Contributor

oli-obk commented Jun 5, 2025

cool, this seems really useful!

@GuillaumeGomez
Copy link
Member Author

For now I only know rust-for-linux as potential users, we'll see if more users will appear in the future.

@bors
Copy link
Collaborator

bors commented Jun 8, 2025

☔ The latest upstream changes (presumably #142181) made this pull request unmergeable. Please resolve the merge conflicts.

@GuillaumeGomez
Copy link
Member Author

Setting @aDotInTheVoid as reviewer since they already reviewed it and it's another JSON output. :)

r? aDotInTheVoid

@rustbot
Copy link
Collaborator

rustbot commented Jun 10, 2025

Requested reviewer is already assigned to this pull request.

Please choose another assignee.

@rust-log-analyzer

This comment has been minimized.

Comment on lines +614 to +622
"doctest_code": {
"crate_level": "#![allow(unused)]\n",
"code": "let x = 12;\nOk(())",
"wrapper": {
"before": "fn main() { fn _inner() -> core::result::Result<(), impl core::fmt::Debug> {\n",
"after": "\n} _inner().unwrap() }",
"returns_result": true
}
},
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we explain these new fields in the docs below?

At least the difference between original_code and code isn't clear (since at least in this example it is the same value).

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Very good point, gonna add explanations.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done!

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks! It looks much better. Does "naked" mean anything different from original_code? If yes, perhaps we should mention how it differs (or for what one would use one or the other). If not, should we keep both?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let me look more in depth if both fields are required.

@GuillaumeGomez
Copy link
Member Author

Added explanations in the rustdoc book about the new JSON fields.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
O-unix Operating system: Unix-like O-windows Operating system: Windows S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. T-rustdoc-frontend Relevant to the rustdoc-frontend team, which will review and decide on the web UI/UX output.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

8 participants