cargo doc fails when [[example]] specifies doc=true

[kentfredric]

Problem

I was looking through the documentation for [[example]] and it suggests that [[example]] nodes support everything that [lib] supports, as it doesn't clearly specify what it supports in isolation ( similar complaint to #6913 in some ways )

Cargo doesn't complain at all that I've done something wrong by specifying doc = true in an example, and I thought it would be a novel idea to have a list of examples and the examples documentation included in my projects documentation. ( A similar but different request akin to #4508 )

[[example]]
name = "repo-info"
required-features = []

[[example]]
name = "category-info"
required-features = []
doc = true

However, when I do this, cargo doc fails due to the example depending on the including crate, and no glue is passed to anything to make this work ( and I suspect, if it wasn't for this failure, other even more broken things might happen )

 Documenting portage_repo v0.1.0 (/home/kent/rust/portage_repo)
     Running `rustdoc --edition=2018 --crate-name category_info examples/category-info.rs --color always -o /home/kent/rust/portage_repo/target/doc --cfg 'feature="default"' --cfg 'feature="external_doc"' --cfg 'feature="nightly"' --cfg 'feature="non_exhaustive"' -L dependency=/home/kent/rust/portage_repo/target/debug/deps --extern failure=/home/kent/rust/portage_repo/target/debug/deps/libfailure-98af8e1b378b64dc.rmeta --extern libc=/home/kent/rust/portage_repo/target/debug/deps/liblibc-bf50700fa6989cfc.rmeta -Z unstable-options --disable-minification --enable-index-page --extern-html-root-url 'failure=https://docs.rs/failure/0.1.5' --extern-html-root-url 'libc=https://docs.rs/libc/0.2.58'`
     Running `rustdoc --edition=2018 --crate-name portage_repo src/lib.rs --color always -o /home/kent/rust/portage_repo/target/doc --cfg 'feature="default"' --cfg 'feature="external_doc"' --cfg 'feature="nightly"' --cfg 'feature="non_exhaustive"' -L dependency=/home/kent/rust/portage_repo/target/debug/deps --extern failure=/home/kent/rust/portage_repo/target/debug/deps/libfailure-98af8e1b378b64dc.rmeta --extern libc=/home/kent/rust/portage_repo/target/debug/deps/liblibc-bf50700fa6989cfc.rmeta -Z unstable-options --disable-minification --enable-index-page --extern-html-root-url 'failure=https://docs.rs/failure/0.1.5' --extern-html-root-url 'libc=https://docs.rs/libc/0.2.58'`
error[E0432]: unresolved import `portage_repo`
 --> examples/category-info.rs:8:5
  |
8 | use portage_repo::Category;
  |     ^^^^^^^^^^^^ use of undeclared type or module `portage_repo`

error: Compilation failed, aborting rustdoc

error: aborting due to 2 previous errors

For more information about this error, try `rustc --explain E0432`.
error: Could not document `portage_repo`.

I'm not sure what behaviour I expected exactly, I just expected it to either execute properly, or cargo should have told me what I'm doing isn't allowed.

If it executed properly, I'd expect that the documentation in the example should turn up "somewhere" in the doc tree, but I wasn't sure where.

Possible Solution(s)

• Cargo could reject this combination early. It would make me slightly sad, but at least I wouldn't be expecting useful behaviour
• Cargo doc could be potentially made to have this work, I'm just undecided about where in the output I'd expect to see them. IME, examples should be documented as children of the parent crate, similarly to modules in the parent crate, even though they're not technically "inside" the crate, there's no other logical place to put them. ( Maybe in the crate-level all-items list under a section like "Examples" similar to the list of Structs and Enums? IDK )
• Documentation has room for improvement in either case, as the exploration of undocumented behaviour is ultimately a side effect of the inadequacy of the documentation.

Notes

Output of cargo version: cargo 1.37.0-nightly (545f354 2019-05-23)