src/test/run-make/coverage/doctest.rs

   1 //! This test ensures that code from doctests is properly re-mapped.
   2 //! See <https://github.com/rust-lang/rust/issues/79417> for more info.
   3 //!
   4 //! Just some random code:
   5 //! ```
   6 //! if true {
   7 //!     // this is executed!
   8 //!     assert_eq!(1, 1);
   9 //! } else {
  10 //!     // this is not!
  11 //!     assert_eq!(1, 2);
  12 //! }
  13 //! ```
  14 //!
  15 //! doctest testing external code:
  16 //! ```
  17 //! extern crate doctest_crate;
  18 //! doctest_crate::fn_run_in_doctests(1);
  19 //! ```
  20 //!
  21 //! doctest returning a result:
  22 //! ```
  23 //! #[derive(Debug, PartialEq)]
  24 //! struct SomeError {
  25 //!     msg: String,
  26 //! }
  27 //! let mut res = Err(SomeError { msg: String::from("a message") });
  28 //! if res.is_ok() {
  29 //!     res?;
  30 //! } else {
  31 //!     if *res.as_ref().unwrap_err() == *res.as_ref().unwrap_err() {
  32 //!         println!("{:?}", res);
  33 //!     }
  34 //!     if *res.as_ref().unwrap_err() == *res.as_ref().unwrap_err() {
  35 //!         res = Ok(1);
  36 //!     }
  37 //!     res = Ok(0);
  38 //! }
  39 //! // need to be explicit because rustdoc cant infer the return type
  40 //! Ok::<(), SomeError>(())
  41 //! ```
  42 //!
  43 //! doctest with custom main:
  44 //! ```
  45 //! fn some_func() {
  46 //!     println!("called some_func()");
  47 //! }
  48 //!
  49 //! #[derive(Debug)]
  50 //! struct SomeError;
  51 //!
  52 //! extern crate doctest_crate;
  53 //!
  54 //! fn doctest_main() -> Result<(), SomeError> {
  55 //!     some_func();
  56 //!     doctest_crate::fn_run_in_doctests(2);
  57 //!     Ok(())
  58 //! }
  59 //!
  60 //! // this `main` is not shown as covered, as it clashes with all the other
  61 //! // `main` functions that were automatically generated for doctests
  62 //! fn main() -> Result<(), SomeError> {
  63 //!     doctest_main()
  64 //! }
  65 //! ```
  66
  67 /// doctest attached to fn testing external code:
  68 /// ```
  69 /// extern crate doctest_crate;
  70 /// doctest_crate::fn_run_in_doctests(3);
  71 /// ```
  72 ///
  73 fn main() {
  74     if true {
  75         assert_eq!(1, 1);
  76     } else {
  77         assert_eq!(1, 2);
  78     }
  79 }
  80
  81 // FIXME(Swatinem): Fix known issue that coverage code region columns need to be offset by the
  82 // doc comment line prefix (`///` or `//!`) and any additional indent (before or after the doc
  83 // comment characters). This test produces `llvm-cov show` results demonstrating the problem.
  84 //
  85 // One of the above tests now includes: `derive(Debug, PartialEq)`, producing an `llvm-cov show`
  86 // result with a distinct count for `Debug`, denoted by `^1`, but the caret points to the wrong
  87 // column. Similarly, the `if` blocks without `else` blocks show `^0`, which should point at, or
  88 // one character past, the `if` block's closing brace. In both cases, these are most likely off
  89 // by the number of characters stripped from the beginning of each doc comment line: indent
  90 // whitespace, if any, doc comment prefix (`//!` in this case) and (I assume) one space character
  91 // (?). Note, when viewing `llvm-cov show` results in `--color` mode, the column offset errors are
  92 // more pronounced, and show up in more places, with background color used to show some distinct
  93 // code regions with different coverage counts.
  94 //
  95 // NOTE: Since the doc comment line prefix may vary, one possible solution is to replace each
  96 // character stripped from the beginning of doc comment lines with a space. This will give coverage
  97 // results the correct column offsets, and I think it should compile correctly, but I don't know
  98 // what affect it might have on diagnostic messages from the compiler, and whether anyone would care
  99 // if the indentation changed. I don't know if there is a more viable solution.