Intradoc links are broken when building with no default features

[lopopolo]

bstr has errors building documentation when doing so with --no-default-features.

$ cargo doc --no-default-features
warning: unresolved link to `ByteVec::unescape_bytes`
    --> src/ext_slice.rs:2783:40
     |
2783 |     /// The dual of this function is [`ByteVec::unescape_bytes`].
     |                                        ^^^^^^^^^^^^^^^^^^^^^^^ no item named `ByteVec` in scope
     |
     = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default

warning: unresolved link to `BString`
    --> src/ext_slice.rs:2786:42
     |
2786 |     /// implementation on [`BStr`] and [`BString`]. The `Debug` implementations
     |                                          ^^^^^^^ no item named `BString` in scope
     |
     = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`

warning: `bstr` (lib doc) generated 2 warnings
    Finished dev [unoptimized + debuginfo] target(s) in 0.03s

Additionally, the vast majority of intra-doc linking in this crate is hardcoding links to HTML pages that rustdoc generates. Linking in this way prevents rustdoc from properly linting whether the items being referenced exist (which is especially nice in the presence of conditional compilation).

bstr/src/lib.rs

Lines 338 to 354 in b3cab19

	* [`ByteVec::from_os_string`](trait.ByteVec.html#method.from_os_string)
	* [`ByteVec::from_os_str_lossy`](trait.ByteVec.html#method.from_os_str_lossy)
	* [`ByteVec::from_path_buf`](trait.ByteVec.html#method.from_path_buf)
	* [`ByteVec::from_path_lossy`](trait.ByteVec.html#method.from_path_lossy)
	* [`ByteVec::into_os_string`](trait.ByteVec.html#method.into_os_string)
	* [`ByteVec::into_os_string_lossy`](trait.ByteVec.html#method.into_os_string_lossy)
	* [`ByteVec::into_path_buf`](trait.ByteVec.html#method.into_path_buf)
	* [`ByteVec::into_path_buf_lossy`](trait.ByteVec.html#method.into_path_buf_lossy)
	For byte string slices, they are:
	* [`ByteSlice::from_os_str`](trait.ByteSlice.html#method.from_os_str)
	* [`ByteSlice::from_path`](trait.ByteSlice.html#method.from_path)
	* [`ByteSlice::to_os_str`](trait.ByteSlice.html#method.to_os_str)
	* [`ByteSlice::to_os_str_lossy`](trait.ByteSlice.html#method.to_os_str_lossy)
	* [`ByteSlice::to_path`](trait.ByteSlice.html#method.to_path)
	* [`ByteSlice::to_path_lossy`](trait.ByteSlice.html#method.to_path_lossy)

Example links that are broken are this link to BString on the BStr type docs:

I've found adding this env var to CI and building the docs as part of the CI steps that test the feature matrix to be useful in preventing regressions here:

RUSTDOCFLAGS="-D warnings -D rustdoc::broken_intra_doc_links --cfg docsrs"

[BurntSushi]

So the direct HTML links were written that way because they were written well before intra doc links... Someone "just" has to go through and fix them.

I'm aware of the first issue, which is that some links are broken when not all features are enabled. I don't know how to fix that. Unless there's some elegant solution, I think we just have to live with the warnings.

[lopopolo]

for the broken links when not all features are enabled, I've been using a trick with cfg_attr and doc attributes to fill in hardcoded links to docs.rs or the std docs when features are not activated:

Like this: https://github.com/artichoke/roe/blob/2f4f7cb539eee4bef8ef8b24c523e18126b31b07/src/lib.rs#L73-L94.

//!
#![cfg_attr(
    not(feature = "std"),
    doc = "[`std`]: https://doc.rust-lang.org/std/index.html"
)]
#![cfg_attr(
    not(feature = "std"),
    doc = "[`std::error::Error`]: https://doc.rust-lang.org/std/error/trait.Error.html"
)]
#![cfg_attr(
    not(feature = "alloc"),
    doc = "[`alloc`]: https://doc.rust-lang.org/alloc/index.html"
)]
#![cfg_attr(feature = "alloc", doc = "[`String`]: alloc::string::String")]
#![cfg_attr(
    not(feature = "alloc"),
    doc = "[`String`]: https://doc.rust-lang.org/alloc/string/struct.String.html"
)]
#![cfg_attr(feature = "alloc", doc = "[`Vec`]: alloc::vec::Vec")]
#![cfg_attr(
    not(feature = "alloc"),
    doc = "[`Vec`]: https://doc.rust-lang.org/alloc/vec/struct.Vec.html"
)]
//! [Unicode case mapping]: https://unicode.org/faq/casemap_charprop.html#casemap
//! [conventionally UTF-8 binary strings]: https://docs.rs/bstr/0.2.*/bstr/#when-should-i-use-byte-strings

[BurntSushi]

It's a neat trick but I don't see myself doing that. Waaaaay too much work and way too messy. I would much rather just have warnings and broken links personally.