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

"edition": null,
"added_css_classes": [],
"unknown": []
"file":"$DIR/extract-doctests-result.rs",
Copy link
Contributor

Choose a reason for hiding this comment

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

I think we should make it clear that the filename here is the filename of the file that contains the doctest. Since we're using the name src/lib.rs above, shouldn't we use the same name here?

also, aren't the $DIR placeholders are added by compiletest, not rustdoc?

"returns_result":true
}
},
"name":"$DIR/extract-doctests-result.rs - (line 8)"
Copy link
Contributor

Choose a reason for hiding this comment

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

I don't think copy-pasting the JSON from extract-doctests-results.stdout is 100% correct here, since things like line numbers won't be the same.

@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.

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.

6 participants