Auto merge of #140527 - GuillaumeGomez:doctest-main-fn, r=notriddle

Emit a warning if the doctest `main` function will not be run
Fixes#140310.
I think we could try to go much further like adding a "link" (ie UI annotations) on the `main` function in the doctest. However that will require some more computation, not sure if it's worth it or not. Can still be done in a follow-up if we want it.
For now, this PR does two things:
1. Pass the `DiagCtxt` to the doctest parser to emit the warning.
2. Correctly generate the `Span` to where the doctest is starting (I hope the way I did it isn't too bad either...).
cc `@fmease`
r? `@notriddle`

Author: bors

src/librustdoc/doctest.rs

@@ -12,7 +12,7 @@ use std::sync::atomic::{AtomicUsize, Ordering};
 use std::sync::{Arc,Mutex};
 use std::{panic, str};
 
-pub(crate)use make::DocTestBuilder;
+pub(crate)use make::{BuildDocTestBuilder,DocTestBuilder};
 pub(crate)use markdown::test as test_markdown;
 use rustc_data_structures::fx::{FxHashMap,FxIndexMap,FxIndexSet};
 use rustc_errors::emitter::HumanReadableErrorType;
@@ -23,9 +23,9 @@ use rustc_hir::def_id::LOCAL_CRATE;
 use rustc_interface::interface;
 use rustc_session::config::{self,CrateType,ErrorOutputType,Input};
 use rustc_session::lint;
-use rustc_span::FileName;
 use rustc_span::edition::Edition;
 use rustc_span::symbol::sym;
+use rustc_span::{FileName,Span};
 use rustc_target::spec::{Target,TargetTuple};
 use tempfile::{BuilderasTempFileBuilder,TempDir};
 use tracing::debug;
@@ -197,7 +197,7 @@ pub(crate) fn run(dcx: DiagCtxtHandle<'_>, input: Input, options: RustdocOptions
 }
 }else{
 letmut collector = CreateRunnableDocTests::new(options, opts);
- tests.into_iter().for_each(|t| collector.add_test(t));
+ tests.into_iter().for_each(|t| collector.add_test(t,Some(compiler.sess.dcx())));
 
 Ok(Some(collector))
 }
@@ -847,6 +847,7 @@ pub(crate) struct ScrapedDocTest {
 langstr:LangString,
 text:String,
 name:String,
+span:Span,
 }
 
 implScrapedDocTest{
@@ -856,6 +857,7 @@ impl ScrapedDocTest {
 logical_path:Vec<String>,
 langstr:LangString,
 text:String,
+span:Span,
 ) -> Self{
 letmut item_path = logical_path.join("::");
  item_path.retain(|c| c != ' ');
@@ -865,7 +867,7 @@ impl ScrapedDocTest {
 let name =
 format!("{} - {item_path}(line {line})", filename.prefer_remapped_unconditionaly());
 
-Self{ filename, line, langstr, text, name }
+Self{ filename, line, langstr, text, name, span}
 }
 fnedition(&self,opts:&RustdocOptions) -> Edition{
 self.langstr.edition.unwrap_or(opts.edition)
@@ -921,7 +923,7 @@ impl CreateRunnableDocTests {
 }
 }
 
-fnadd_test(&mutself,scraped_test:ScrapedDocTest){
+fnadd_test(&mutself,scraped_test:ScrapedDocTest,dcx:Option<DiagCtxtHandle<'_>>){
 // For example `module/file.rs` would become `module_file_rs`
 let file = scraped_test
 .filename
@@ -945,14 +947,14 @@ impl CreateRunnableDocTests {
 );
 
 let edition = scraped_test.edition(&self.rustdoc_options);
-let doctest = DocTestBuilder::new(
-&scraped_test.text,
-Some(&self.opts.crate_name),
-edition,
-self.can_merge_doctests,
-Some(test_id),
-Some(&scraped_test.langstr),
-);
+let doctest = BuildDocTestBuilder::new(&scraped_test.text)
+.crate_name(&self.opts.crate_name)
+.edition(edition)
+.can_merge_doctests(self.can_merge_doctests)
+.test_id(test_id)
+.lang_str(&scraped_test.langstr)
+.span(scraped_test.span)
+.build(dcx);
 let is_standalone = !doctest.can_be_merged
  || scraped_test.langstr.compile_fail
  || scraped_test.langstr.test_harness

src/librustdoc/doctest/extracted.rs

@@ -5,7 +5,7 @@
 
 use serde::Serialize;
 
-usesuper::{DocTestBuilder,ScrapedDocTest};
+usesuper::{BuildDocTestBuilder,ScrapedDocTest};
 usecrate::config::OptionsasRustdocOptions;
 usecrate::html::markdown;
 
@@ -35,16 +35,13 @@ impl ExtractedDocTests {
 ){
 let edition = scraped_test.edition(options);
 
-letScrapedDocTest{ filename, line, langstr, text, name } = scraped_test;
+letScrapedDocTest{ filename, line, langstr, text, name, ..} = scraped_test;
 
-let doctest = DocTestBuilder::new(
-&text,
-Some(&opts.crate_name),
- edition,
-false,
-None,
-Some(&langstr),
-);
+let doctest = BuildDocTestBuilder::new(&text)
+.crate_name(&opts.crate_name)
+.edition(edition)
+.lang_str(&langstr)
+.build(None);
 let(full_test_code, size) = doctest.generate_unique_doctest(
 &text,
  langstr.test_harness,

src/librustdoc/doctest/make.rs

@@ -8,14 +8,14 @@ use std::sync::Arc;
 use rustc_ast::token::{Delimiter,TokenKind};
 use rustc_ast::tokenstream::TokenTree;
 use rustc_ast::{selfas ast,AttrStyle,HasAttrs,StmtKind};
-use rustc_errors::ColorConfig;
 use rustc_errors::emitter::stderr_destination;
+use rustc_errors::{ColorConfig,DiagCtxtHandle};
 use rustc_parse::new_parser_from_source_str;
 use rustc_session::parse::ParseSess;
-use rustc_span::edition::Edition;
+use rustc_span::edition::{DEFAULT_EDITION,Edition};
 use rustc_span::source_map::SourceMap;
 use rustc_span::symbol::sym;
-use rustc_span::{FileName, kw};
+use rustc_span::{DUMMY_SP,FileName,Span, kw};
 use tracing::debug;
 
 usesuper::GlobalTestOptions;
@@ -35,41 +35,86 @@ struct ParseSourceInfo {
 maybe_crate_attrs:String,
 }
 
-/// This struct contains information about the doctest itself which is then used to generate
-/// doctest source code appropriately.
-pub(crate)structDocTestBuilder{
-pub(crate)supports_color:bool,
-pub(crate)already_has_extern_crate:bool,
-pub(crate)has_main_fn:bool,
-pub(crate)crate_attrs:String,
-/// If this is a merged doctest, it will be put into `everything_else`, otherwise it will
-/// put into `crate_attrs`.
-pub(crate)maybe_crate_attrs:String,
-pub(crate)crates:String,
-pub(crate)everything_else:String,
-pub(crate)test_id:Option<String>,
-pub(crate)invalid_ast:bool,
-pub(crate)can_be_merged:bool,
+/// Builder type for `DocTestBuilder`.
+pub(crate)structBuildDocTestBuilder<'a>{
+source:&'astr,
+crate_name:Option<&'astr>,
+edition:Edition,
+can_merge_doctests:bool,
+// If `test_id` is `None`, it means we're generating code for a code example "run" link.
+test_id:Option<String>,
+lang_str:Option<&'aLangString>,
+span:Span,
 }
 
-implDocTestBuilder{
-pub(crate)fnnew(
-source:&str,
-crate_name:Option<&str>,
-edition:Edition,
-can_merge_doctests:bool,
-// If `test_id` is `None`, it means we're generating code for a code example "run" link.
-test_id:Option<String>,
-lang_str:Option<&LangString>,
-) -> Self{
+impl<'a>BuildDocTestBuilder<'a>{
+pub(crate)fnnew(source:&'astr) -> Self{
+Self{
+ source,
+crate_name:None,
+edition:DEFAULT_EDITION,
+can_merge_doctests:false,
+test_id:None,
+lang_str:None,
+span:DUMMY_SP,
+}
+}
+
+#[inline]
+pub(crate)fncrate_name(mutself,crate_name:&'astr) -> Self{
+self.crate_name = Some(crate_name);
+self
+}
+
+#[inline]
+pub(crate)fncan_merge_doctests(mutself,can_merge_doctests:bool) -> Self{
+self.can_merge_doctests = can_merge_doctests;
+self
+}
+
+#[inline]
+pub(crate)fntest_id(mutself,test_id:String) -> Self{
+self.test_id = Some(test_id);
+self
+}
+
+#[inline]
+pub(crate)fnlang_str(mutself,lang_str:&'aLangString) -> Self{
+self.lang_str = Some(lang_str);
+self
+}
+
+#[inline]
+pub(crate)fnspan(mutself,span:Span) -> Self{
+self.span = span;
+self
+}
+
+#[inline]
+pub(crate)fnedition(mutself,edition:Edition) -> Self{
+self.edition = edition;
+self
+}
+
+pub(crate)fnbuild(self,dcx:Option<DiagCtxtHandle<'_>>) -> DocTestBuilder{
+letBuildDocTestBuilder{
+ source,
+ crate_name,
+ edition,
+ can_merge_doctests,
+// If `test_id` is `None`, it means we're generating code for a code example "run" link.
+ test_id,
+ lang_str,
+ span,
+} = self;
 let can_merge_doctests = can_merge_doctests
  && lang_str.is_some_and(|lang_str| {
  !lang_str.compile_fail && !lang_str.test_harness && !lang_str.standalone_crate
 });
 
 let result = rustc_driver::catch_fatal_errors(|| {
  rustc_span::create_session_if_not_set_then(edition, |_| {
-parse_source(source,&crate_name)
+parse_source(source,&crate_name, dcx, span)
 })
 });
 
@@ -87,7 +132,7 @@ impl DocTestBuilder {
 else{
 // If the AST returned an error, we don't want this doctest to be merged with the
 // others.
-returnSelf::invalid(
+returnDocTestBuilder::invalid(
 String::new(),
 String::new(),
 String::new(),
@@ -107,7 +152,7 @@ impl DocTestBuilder {
 // If this is a merged doctest and a defined macro uses `$crate`, then the path will
 // not work, so better not put it into merged doctests.
  && !(has_macro_def && everything_else.contains("$crate"));
-Self{
+DocTestBuilder{
  supports_color,
  has_main_fn,
  crate_attrs,
@@ -120,7 +165,26 @@ impl DocTestBuilder {
  can_be_merged,
 }
 }
+}
 
+/// This struct contains information about the doctest itself which is then used to generate
+/// doctest source code appropriately.
+pub(crate)structDocTestBuilder{
+pub(crate)supports_color:bool,
+pub(crate)already_has_extern_crate:bool,
+pub(crate)has_main_fn:bool,
+pub(crate)crate_attrs:String,
+/// If this is a merged doctest, it will be put into `everything_else`, otherwise it will
+/// put into `crate_attrs`.
+pub(crate)maybe_crate_attrs:String,
+pub(crate)crates:String,
+pub(crate)everything_else:String,
+pub(crate)test_id:Option<String>,
+pub(crate)invalid_ast:bool,
+pub(crate)can_be_merged:bool,
+}
+
+implDocTestBuilder{
 fninvalid(
 crate_attrs:String,
 maybe_crate_attrs:String,
@@ -289,7 +353,12 @@ fn reset_error_count(psess: &ParseSess) {
 
 constDOCTEST_CODE_WRAPPER:&str = "fn f(){";
 
-fnparse_source(source:&str,crate_name:&Option<&str>) -> Result<ParseSourceInfo,()>{
+fnparse_source(
+source:&str,
+crate_name:&Option<&str>,
+parent_dcx:Option<DiagCtxtHandle<'_>>,
+span:Span,
+) -> Result<ParseSourceInfo,()>{
 use rustc_errors::DiagCtxt;
 use rustc_errors::emitter::{Emitter,HumanEmitter};
 use rustc_span::source_map::FilePathMapping;
@@ -466,8 +535,17 @@ fn parse_source(source: &str, crate_name: &Option<&str>) -> Result<ParseSourceIn
 }
 }
 if has_non_items {
-// FIXME: if `info.has_main_fn` is `true`, emit a warning here to mention that
-// this code will not be called.
+if info.has_main_fn
+ && letSome(dcx) = parent_dcx
+ && !span.is_dummy()
+{
+ dcx.span_warn(
+ span,
+"the `main` function of this doctest won't be run as it contains \
+ expressions at the top level, meaning that the whole doctest code will be \
+ wrapped in a function",
+);
+}
  info.has_main_fn = false;
 }
 Ok(info)

src/librustdoc/doctest/markdown.rs

@@ -4,7 +4,7 @@ use std::fs::read_to_string;
 use std::sync::{Arc,Mutex};
 
 use rustc_session::config::Input;
-use rustc_span::FileName;
+use rustc_span::{DUMMY_SP,FileName};
 use tempfile::tempdir;
 
 usesuper::{
@@ -24,7 +24,14 @@ impl DocTestVisitor for MdCollector {
 let filename = self.filename.clone();
 // First line of Markdown is line 1.
 let line = 1 + rel_line.offset();
-self.tests.push(ScrapedDocTest::new(filename, line,self.cur_path.clone(), config, test));
+self.tests.push(ScrapedDocTest::new(
+ filename,
+ line,
+self.cur_path.clone(),
+ config,
+ test,
+DUMMY_SP,
+));
 }
 
 fnvisit_header(&mutself,name:&str,level:u32){
@@ -107,7 +114,7 @@ pub(crate) fn test(input: &Input, options: Options) -> Result<(), String> {
 find_testable_code(&input_str,&mut md_collector, codes,None);
 
 letmut collector = CreateRunnableDocTests::new(options.clone(), opts);
- md_collector.tests.into_iter().for_each(|t| collector.add_test(t));
+ md_collector.tests.into_iter().for_each(|t| collector.add_test(t,None));
 letCreateRunnableDocTests{ opts, rustdoc_options, standalone_tests, mergeable_tests, .. } =
  collector;
 crate::doctest::run_tests(