From 7d007d448ea5423d2c19dc293d7960f1eacf4bb7 Mon Sep 17 00:00:00 2001 From: Martin Geisler Date: Sat, 9 Sep 2023 16:57:26 +0200 Subject: [PATCH] Explain the use of `html_root_url` MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The attribute is no longer recommended by the API guidelines, though there are use cases for people who host their documentation themselves and thus don’t use docs.rs. This should make it a little clearer when to use `assert_html_root_url_updated!`. --- src/lib.rs | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index f68688f..fe4d9fa 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -146,14 +146,17 @@ macro_rules! assert_markdown_deps_updated { /// Assert that the `html_root_url` attribute is up to date. /// -/// Library code is [expected to set `html_root_url`][api-guidelines] -/// to point to docs.rs so that rustdoc can generate correct links -/// when referring to this crate. +/// Library crates can [set `html_root_url`][api-guidelines] to point +/// to their documentation so that `cargo doc --no-deps` in other +/// projects can generate correct links when referring the library. /// /// The macro will call [`check_html_root_url`] on the file name given /// in order to check that the `html_root_url` is points to the -/// current version of your package documentation on docs.rs. The -/// package name is automatically taken from the `$CARGO_PKG_NAME` +/// current version of your package documentation on docs.rs. Use +/// [`assert_contains_regex!`] instead if you don't host the +/// documentation on docs.rs. +/// +/// The package name is automatically taken from the `$CARGO_PKG_NAME` /// environment variable and the version is taken from /// `$CARGO_PKG_VERSION`. These environment variables are /// automatically set by Cargo when compiling your crate.