From c973f97b73a6cd8d4d63938424dc91d07e7b92f3 Mon Sep 17 00:00:00 2001
From: Julien Cretin <cretin@google.com>
Date: Thu, 5 Oct 2023 21:28:58 +0200
Subject: [PATCH] Use doc_auto_cfg to automatically document gating features
 (#82)

Fixes #73
---
 lib/CHANGELOG.md |  1 +
 lib/Cargo.toml   |  4 ++++
 lib/src/lib.rs   | 37 +------------------------------------
 3 files changed, 6 insertions(+), 36 deletions(-)

diff --git a/lib/CHANGELOG.md b/lib/CHANGELOG.md
index 9314c10..4fb80a5 100644
--- 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
index 7cf7926..fc17658 100644
--- 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
index 392de2c..e702648 100644
--- 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);