Description
Using doc(include = .... ) allows cargo test --doc to compile and test ``` fenced sections in the markdown.
However, the reported origins for these tests becomes completely confusing, as the line numbers appear to correlate to where you might expect to see the content, if the content was naively inlined.
Running `rustdoc --edition=2018 --test /home/kent/rust/grease/src/lib.rs --crate-name grease -L dependency=/home/kent/rust/grease/target/debug/deps -L native=/home/kent/rust/grease/target/debug/build/backtrace-sys-40a4a1ea875db113/out -L dependency=/home/kent/rust/grease/target/debug/deps --cfg 'feature="default"' --cfg 'feature="external_doc"' --extern failure=/home/kent/rust/grease/target/debug/deps/libfailure-dae5569a6045eb7d.rlib --extern grease=/home/kent/rust/grease/target/debug/deps/libgrease-40e583d4df6fae15.rlib`
running 19 tests
test src/repository.rs - repository::Repository (line 44) ... ok
test src/repository.rs - repository::Repository (line 61) ... ok
test src/repository.rs - repository::Repository (line 83) ... ok
test src/repository.rs - repository (line 6) ... ok
test src/repository/category.rs - repository::category::Category (line 40) ... ok
test src/repository.rs - repository::Repository (line 96) ... ok
test src/repository/category.rs - repository::category::Category (line 57) ... ok
test src/repository/category.rs - repository::category::Category (line 12) ... ok
test src/repository/category.rs - repository::category::CategoryFileIterator (line 106) ... ok
test src/repository/category.rs - repository::category::CategoryFileIterator (line 156) ... ok
test src/repository/category.rs - repository::category::Category (line 70) ... ok
test src/repository/ebuild.rs - repository::ebuild::Ebuild (line 42) ... ok
test src/repository/ebuild.rs - repository::ebuild::Ebuild (line 6) ... ok
test src/repository/ebuild.rs - repository::ebuild::Ebuild (line 64) ... ok
test src/repository/ebuild.rs - repository::ebuild::Ebuild (line 84) ... ok
test src/repository/package.rs - repository::package::Package (line 34) ... ok
test src/repository/package.rs - repository::package::Package (line 55) ... ok
test src/repository/package.rs - repository::package::Package (line 5) ... ok
test src/repository/package.rs - repository::package::Package (line 68) ... ok
However, literally none of the files mentioned have rustdoc code blocks in them, and 100% of these tests are from included files.
For example, reading category.rs at the expected offsets: ( with 2 lines either side for context )
test src/repository/category.rs - repository::category::Category (line 12) ... ok
/// Represents a concrete Gentoo category
#[cfg_attr(
feature = "external_doc",test src/repository/category.rs - repository::category::Category (line 40) ... ok
/// Return the name of the category
pub fn name(&self) -> String { self.category.to_owned() }
}test src/repository/category.rs - repository::category::Category (line 57) ... ok
#[derive(Fail, Debug)]
#[fail(display = "An error occurred iterating a category file")]
pub enum CategoryFileError {test src/repository/category.rs - repository::category::Category (line 70) ... ok
#[fail(display = "Path <{:?}> encountered decoding errors", _1)]
FileDecodeError(#[fail(cause)] io::Error, PathBuf),
/// An IO error occurred reading a file
test src/repository/category.rs - repository::category::CategoryFileIterator (line 106) ... ok
})
.and_then(|meta| {
if meta.is_dir() {test src/repository/category.rs - repository::category::CategoryFileIterator (line 156) ... ok
( File only has 145 lines )
Whereas, if I take the include lines:
category.rs 12-15
#[cfg_attr(
feature = "external_doc",
doc(include = "repository/struct.Category.md")
)]category.rs 77-80
/// Iterate a `categories` file in a portage repository
#[cfg_attr(
feature = "external_doc",
doc(include = "repository/struct.CategoryFileIterator.md")
)]And do a little manual derviation to find source lines:
test src/repository/category.rs - repository::category::Category (line 12) ... ok
12 - 12 => 0
struct.Category.md 0-7
```rust
# use grease::repository::Category;
# use std::path::Path;
let c = Category::new("/usr/portage", "dev-perl");
assert_eq!(c.path(), Path::new("/usr/portage/dev-perl"));
assert_eq!(c.name(), "dev-perl");
```
test src/repository/category.rs - repository::category::Category (line 40) ... ok
40 - 12 => 28
struct.Category.md 28-37
```rust
# use grease::repository::{Category, Repository};
# use std::path::Path;
Category::new("/usr/portage", "dev-perl");
Category::new(String::from("/usr/portage"), String::from("dev-perl"));
// Using Repositories implementation of Into
let r = Repository::new("/usr/portage");
Category::new(&r, "dev-perl");
```
test src/repository/category.rs - repository::category::Category (line 57) ... ok
57 - 12 -> 45
struct.Category.md 45-56
## AsRef\
```rust
# use grease::repository::Category;
# use std::path::{Path,PathBuf};
fn demo(path: P) -> ()
where
P: AsRef,
{
assert_eq!(Path::new("/usr/portage/dev-perl"), path.as_ref());
}
demo(Category::new("/usr/portage", "dev-perl"));
```
test src/repository/category.rs - repository::category::Category (line 70) ... ok
70 - 12 -> 58
struct.Category.md 58-73
## Into\
```rust
# use grease::repository::Category;
# use std::path::{Path, PathBuf};
fn demo(path: P) -> ()
where
P: Into,
{
assert_eq!(Path::new("/usr/portage/dev-perl"), path.into());
}
let c = Category::new("/usr/portage", "dev-perl");
// Using From<&Category>
demo(&c);
// Using From
demo(c);
```
test src/repository/category.rs - repository::category::CategoryFileIterator (line 106) ... ok
106 - 77 -> 29
struct.CategoryFileIterator.md 29-46
```no_run
use grease::repository::CategoryFileIterator;
match CategoryFileIterator::for_file(
"/usr/portage",
"/usr/portage/profiles/categories",
) {
Err(e) => panic!(e),
Ok(iterator) => {
for category in iterator {
match category {
Err(e) => panic!(e),
Ok(c) => println!("{}", c.name()),
}
}
},
}
```
test src/repository/category.rs - repository::category::CategoryFileIterator (line 156) ... ok
156 - 77 -> 79
struct.CategoryFileIterator.md 79-89
```no_run
use grease::repository::CategoryFileIterator;
let iterator = CategoryFileIterator::for_file(
"/usr/portage",
"/usr/portage/profiles/categories",
);
for item_result in iterator.unwrap() {
println!("{}", item_result.unwrap().name());
}
```
As you can see, manual re-calculation provides reasonable locations, which suggests part of the problem in display ( though my method seems to have off-by-one errors for some reason, shrug )
I believe this bug should block stabilization of this feature #44732