Use doc_auto_cfg to automatically document gating features (#82)

Fixes #73
ia0 · Oct 5, 2023 · c973f97 · c973f97
1 parent b647a5b
commit c973f97
Show file tree

Hide file tree

Showing 3 changed files with 6 additions and 36 deletions.
diff --git a/lib/CHANGELOG.md b/lib/CHANGELOG.md
@@ -8,6 +8,7 @@
 
 ### Patch
 
+- Use `doc_auto_cfg` to show gating features (fixes #73)
 - Hide the documentation of the `Encoding` implementation (fixes #75)
 
 ## 2.4.0

diff --git a/lib/Cargo.toml b/lib/Cargo.toml
@@ -13,6 +13,10 @@ documentation = "https://docs.rs/data-encoding"
 description = "Efficient and customizable data-encoding functions like base64, base32, and hex"
 include = ["Cargo.toml", "LICENSE", "README.md", "src/lib.rs"]
 
+# TODO: Remove this once doc_auto_cfg is in the MSRV.
+[package.metadata.docs.rs]
+rustdoc-args = ["--cfg=docsrs"]
+
 [features]
 default = ["std"]
 alloc = []

diff --git a/lib/src/lib.rs b/lib/src/lib.rs
@@ -144,6 +144,7 @@
 //! [wrapping]: struct.Specification.html#structfield.wrap
 
 #![no_std]
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
 #![warn(unused_results, missing_docs)]
 
 #[cfg(feature = "alloc")]
@@ -805,10 +806,6 @@ fn decode_wrap_mut<B: Static<usize>, M: Static<bool>, P: Static<bool>, I: Static
 /// assert_eq!(msb.encode(&[0b01010011]), "01010011");
 /// assert_eq!(lsb.encode(&[0b01010011]), "11001010");
 /// ```
-///
-/// # Features
-///
-/// Requires the `alloc` feature.
 #[derive(Debug, Copy, Clone, PartialEq, Eq)]
 #[cfg(feature = "alloc")]
 pub enum BitOrder {
@@ -879,10 +876,6 @@ pub struct Encoding(#[doc(hidden)] pub InternalEncoding);
 /// of the `to` field. The second to the second. Etc.
 ///
 /// See [Specification](struct.Specification.html) for more information.
-///
-/// # Features
-///
-/// Requires the `alloc` feature.
 #[derive(Debug, Clone)]
 #[cfg(feature = "alloc")]
 pub struct Translate {
@@ -896,10 +889,6 @@ pub struct Translate {
 /// How to wrap the output when encoding
 ///
 /// See [Specification](struct.Specification.html) for more information.
-///
-/// # Features
-///
-/// Requires the `alloc` feature.
 #[derive(Debug, Clone)]
 #[cfg(feature = "alloc")]
 pub struct Wrap {
@@ -1154,10 +1143,6 @@ pub struct Wrap {
 /// assert_eq!(base.decode(b"BOIl"), base.decode(b"b011"));
 /// ```
 ///
-/// # Features
-///
-/// Requires the `alloc` feature.
-///
 /// [base-conversion]: https://en.wikipedia.org/wiki/Positional_notation#Base_conversion
 /// [canonical]: https://tools.ietf.org/html/rfc4648#section-3.5
 #[derive(Debug, Clone)]
@@ -1311,10 +1296,6 @@ impl Encoding {
     /// BASE64.encode_append(input, &mut output);
     /// assert_eq!(output, "Result: SGVsbG8gd29ybGQ=");
     /// ```
-    ///
-    /// # Features
-    ///
-    /// Requires the `alloc` feature.
     #[cfg(feature = "alloc")]
     pub fn encode_append(&self, input: &[u8], output: &mut String) {
         let output = unsafe { output.as_mut_vec() };
@@ -1331,10 +1312,6 @@ impl Encoding {
     /// use data_encoding::BASE64;
     /// assert_eq!(BASE64.encode(b"Hello world"), "SGVsbG8gd29ybGQ=");
     /// ```
-    ///
-    /// # Features
-    ///
-    /// Requires the `alloc` feature.
     #[cfg(feature = "alloc")]
     pub fn encode(&self, input: &[u8]) -> String {
         let mut output = vec![0u8; self.encode_len(input.len())];
@@ -1441,10 +1418,6 @@ impl Encoding {
     /// assert_eq!(BASE64.decode(b"SGVsbA==byB3b3JsZA==").unwrap(), b"Hello world");
     /// ```
     ///
-    /// # Features
-    ///
-    /// Requires the `alloc` feature.
-    ///
     /// [`Length`]: enum.DecodeKind.html#variant.Length
     /// [`Symbol`]: enum.DecodeKind.html#variant.Symbol
     /// [`Trailing`]: enum.DecodeKind.html#variant.Trailing
@@ -1493,10 +1466,6 @@ impl Encoding {
     }
 
     /// Returns the encoding specification
-    ///
-    /// # Features
-    ///
-    /// Requires the `alloc` feature.
     #[cfg(feature = "alloc")]
     pub fn specification(&self) -> Specification {
         let mut specification = Specification::new();
@@ -1567,10 +1536,6 @@ enum SpecificationErrorImpl {
 use crate::SpecificationErrorImpl::*;
 
 /// Specification error
-///
-/// # Features
-///
-/// Requires the `alloc` feature.
 #[derive(Debug, Copy, Clone)]
 #[cfg(feature = "alloc")]
 pub struct SpecificationError(SpecificationErrorImpl);