Replace docsrs cfg with libloading_docs

`docsrs` is a commonly used `cfg` identifier. `libloading`'s
implementation is written in such a way that it cannot compile with this
cfg set, but is still able to produce documentation. This is done so
that the documentation is naturally covering all platform-specific
details in a single page, without users having to e.g. switch between
Windows® and Linux when reading the documentation on `docs.rs`.

The downstream crates may accidentally set this `cfg` for `rustc`
invocations as well, which can then cause them to fail to build, for no
good reason!

Using a cfg specific to a crate (e.g. `libloading_docs`)
more accurately reflects the purpose of this cfg and avoids these
problems altogether.

Fixes #101

.github/workflows/libloading.yml

@@ -43,9 +43,11 @@ jobs:
       - name: Documentation
         uses: actions-rs/cargo@v1
         with:
-          command: doc
-        env:
-          RUSTDOCFLAGS: --cfg docsrs -Drustdoc::broken_intra_doc_links
+          command: rustdoc
+          args: |
+            -Zunstable-options
+            --config
+            'build.rustdogflags=["--cfg", "libloading_docs", "-D", "rustdoc::broken_intra_doc_links"]'
         if: ${{ matrix.rust_toolchain == 'nightly' }}
 
   windows-gnu-test:

Cargo.toml

@@ -3,7 +3,7 @@ name = "libloading"
 # When bumping
 # * Don’t forget to add an entry to `src/changelog.rs`
 # * If bumping to an incompatible version, adjust the documentation in `src/lib.rs`
-version = "0.7.2"
+version = "0.7.3"
 authors = ["Simonas Kazlauskas <libloading@kazlauskas.me>"]
 license = "ISC"
 repository = "https://github.com/nagisa/rust_libloading/"
@@ -30,4 +30,4 @@ static_assertions = "1.1"
 
 [package.metadata.docs.rs]
 all-features = true
-rustdoc-args = ["--cfg", "docsrs"]
+rustdoc-args = ["--cfg", "libloading_docs"]

src/changelog.rs

@@ -1,5 +1,15 @@
 //! The change log.
 
+/// Release 0.7.3 (2022-01-15)
+///
+/// This release has no functional changes.
+///
+/// In this release the `docsrs` `cfg` has been renamed to `libloading_docs` to better reflect that
+/// this `cfg` is intended to be only used by `libloading` and only specifically for the invocation
+/// of `rustdoc` when documenting `libloading`. Setting this `cfg` in any other situation is
+/// unsupported and will not work.
+pub mod r0_7_3 {}
+
 /// Release 0.7.2 (2021-11-14)
 ///
 /// Cargo.toml now specifies the MSRV bounds, which enables tooling to report an early failure when

src/lib.rs

@@ -36,7 +36,7 @@
 //! The compiler will ensure that the loaded function will not outlive the `Library` from which it comes,
 //! preventing the most common memory-safety issues.
 #![cfg_attr(any(unix, windows), deny(missing_docs, clippy::all, unreachable_pub, unused))]
-#![cfg_attr(docsrs, feature(doc_cfg))]
+#![cfg_attr(libloading_docs, feature(doc_cfg))]
 
 pub mod changelog;
 pub mod os;
@@ -45,9 +45,9 @@ mod util;
 mod error;
 pub use self::error::Error;
 
-#[cfg(any(unix, windows, docsrs))]
+#[cfg(any(unix, windows, libloading_docs))]
 mod safe;
-#[cfg(any(unix, windows, docsrs))]
+#[cfg(any(unix, windows, libloading_docs))]
 pub use self::safe::{Library, Symbol};
 
 use std::env::consts::{DLL_PREFIX, DLL_SUFFIX};

src/os/mod.rs

@@ -17,11 +17,11 @@
 //! ```
 
 /// UNIX implementation of dynamic library loading.
-#[cfg(any(unix, docsrs))]
-#[cfg_attr(docsrs, doc(cfg(unix)))]
+#[cfg(any(unix, libloading_docs))]
+#[cfg_attr(libloading_docs, doc(cfg(unix)))]
 pub mod unix;
 
 /// Windows implementation of dynamic library loading.
-#[cfg(any(windows, docsrs))]
-#[cfg_attr(docsrs, doc(cfg(windows)))]
+#[cfg(any(windows, libloading_docs))]
+#[cfg_attr(libloading_docs, doc(cfg(windows)))]
 pub mod windows;

src/os/unix/consts.rs

@@ -43,7 +43,7 @@ pub const RTLD_GLOBAL: c_int = posix::RTLD_GLOBAL;
 /// any other executable object file. This mode of operation is most appropriate for e.g. plugins.
 pub const RTLD_LOCAL: c_int = posix::RTLD_LOCAL;
 
-#[cfg(all(docsrs, not(unix)))]
+#[cfg(all(libloading_docs, not(unix)))]
 mod posix {
     use super::c_int;
     pub(super) const RTLD_LAZY: c_int = !0;
@@ -52,7 +52,7 @@ mod posix {
     pub(super) const RTLD_LOCAL: c_int = !0;
 }
 
-#[cfg(any(not(docsrs), unix))]
+#[cfg(any(not(libloading_docs), unix))]
 mod posix {
     extern crate cfg_if;
     use self::cfg_if::cfg_if;

src/os/unix/mod.rs

@@ -1,8 +1,8 @@
 // A hack for docs.rs to build documentation that has both windows and linux documentation in the
 // same rustdoc build visible.
-#[cfg(all(docsrs, not(unix)))]
+#[cfg(all(libloading_docs, not(unix)))]
 mod unix_imports {}
-#[cfg(any(not(docsrs), unix))]
+#[cfg(any(not(libloading_docs), unix))]
 mod unix_imports {
     pub(super) use std::os::unix::ffi::OsStrExt;
 }

src/os/windows/mod.rs

@@ -1,6 +1,6 @@
 // A hack for docs.rs to build documentation that has both windows and linux documentation in the
 // same rustdoc build visible.
-#[cfg(all(docsrs, not(windows)))]
+#[cfg(all(libloading_docs, not(windows)))]
 mod windows_imports {
     pub(super) enum WORD {}
     pub(super) struct DWORD;
@@ -23,7 +23,7 @@ mod windows_imports {
         pub(crate) const LOAD_LIBRARY_SAFE_CURRENT_DIRS: DWORD = DWORD;
     }
 }
-#[cfg(any(not(docsrs), windows))]
+#[cfg(any(not(libloading_docs), windows))]
 mod windows_imports {
     extern crate winapi;
     pub(super) use self::winapi::shared::minwindef::{WORD, DWORD, HMODULE, FARPROC};

src/safe.rs

@@ -1,17 +1,17 @@
 use super::Error;
-#[cfg(docsrs)]
+#[cfg(libloading_docs)]
 use super::os::unix as imp; // the implementation used here doesn't matter particularly much...
-#[cfg(all(not(docsrs), unix))]
+#[cfg(all(not(libloading_docs), unix))]
 use super::os::unix as imp;
-#[cfg(all(not(docsrs), windows))]
+#[cfg(all(not(libloading_docs), windows))]
 use super::os::windows as imp;
 use std::ffi::OsStr;
 use std::fmt;
 use std::marker;
 use std::ops;
 
 /// A loaded dynamic library.
-#[cfg_attr(docsrs, doc(cfg(any(unix, windows))))]
+#[cfg_attr(libloading_docs, doc(cfg(any(unix, windows))))]
 pub struct Library(imp::Library);
 
 impl Library {
@@ -193,7 +193,7 @@ unsafe impl Sync for Library {}
 /// itself, without taking care to “extract” the function or variable manually most of the time.
 ///
 /// [`Library::get`]: Library::get
-#[cfg_attr(docsrs, doc(cfg(any(unix, windows))))]
+#[cfg_attr(libloading_docs, doc(cfg(any(unix, windows))))]
 pub struct Symbol<'lib, T: 'lib> {
     inner: imp::Symbol<T>,
     pd: marker::PhantomData<&'lib T>,