Open lopopolo opened 12 months ago
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.
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
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.
bstr
has errors building documentation when doing so with--no-default-features
.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).
https://github.com/BurntSushi/bstr/blob/b3cab1905c46ad7de78a032a61eef0437ed7fb58/src/lib.rs#L338-L354
Example links that are broken are this link to
BString
on theBStr
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: