Description
I think this is all working correctly, but I'd like to record the issue in case it trips up anyone else.
If you have a project with default features, and an example requires one of those default features to be enabled, then cargo doc --examples will give an overly general warning, fail to generate example documentation, and possibly fail to complete other generation tasks, but the invocation will report success.
E.g., suppose the correct invocation to run an example is cargo run --example hello-world --features=defaultfeature. If you omit the --features flag you'd see an error like this:
error: target `hello-world` in package `mypackage` requires the features: `defaultfeature`
Consider enabling them by passing, e.g., `--features="defaultfeature"`This tells you exactly what to do, and all is good. But if you try a related cargo doc command cargo doc --examples, you get this error:
warning: target filter `examples` specified, but no targets matched; this is a no-opThis also makes sense; it's a batch command that doesn't have a cargo run equivalent, so it reasonably suppresses the error messages that caused the build of one example bin in the batch to fail.
But if a developer isn't really paying attention, a document-the-world command like cargo doc --no-deps --examples --workspace will appear to succeed, but generate only some of the expected documentation (in my case, it built my subcrate documentation but not the top-level crate, which was just enough for my build script to succeed without my noticing that it had actually failed to complete).
Apologies for this long-winded report; there might be a more concise description of undesirable behavior (perhaps "cargo doc --examples --workspace fails to complete if required features aren't specified"?). I have solved the issue for my own purposes and wanted to spew the whole story here in case it provides more search terms for someone else to find it.