docs: Expose feature-gated APIs with doc(cfg) (#346)

APIs hidden behind features can now be viewed on docs.rs!
All feature-gated modules and structs should be annotated
with a note that mentions the specific feature flag needed
to use the corresponding API.

This primarily fixes a linter warning regarding a link to a
nonexistent integration which was gated behind a feature.
There are other small fixes as well, mostly just hooking up
links that weren't assigned destinations.

While the doc feature is considered unstable, we're taking
advantage of the fact that docs are built with nightly by
default.

Author: relaxolotl

sentry/Cargo.toml

@@ -12,8 +12,12 @@ Sentry (getsentry.com) client for rust ;)
 edition = "2018"
 autoexamples = true
 
+# To build locally:
+# RUSTDOCFLAGS="--cfg doc_cfg" cargo +nightly doc --all-features --open
 [package.metadata.docs.rs]
 all-features = true
+# Defines the configuration attribute `doc_cfg` in order to expose feature-gated docs.
+rustdoc-args = ["--cfg", "doc_cfg"]
 
 [features]
 default = ["backtrace", "contexts", "panic", "transport"]

sentry/src/lib.rs

@@ -104,6 +104,10 @@
 #![doc(html_favicon_url = "https://sentry-brand.storage.googleapis.com/favicon.ico")]
 #![doc(html_logo_url = "https://sentry-brand.storage.googleapis.com/sentry-glyph-black.png")]
 #![warn(missing_docs)]
+// Only enables the `doc_cfg` feature when the `doc_cfg` configuration attribute
+// is defined. Used to expose docs for feature-locked integrations, and other
+// feature-gated documentation.
+#![cfg_attr(doc_cfg, feature(doc_cfg))]
 
 mod defaults;
 mod init;
@@ -171,27 +175,35 @@ pub use crate::init::{init, ClientInitGuard};
 /// [`apply_defaults()`]: ../fn.apply_defaults.html
 pub mod integrations {
     #[cfg(feature = "anyhow")]
+    #[cfg_attr(doc_cfg, doc(cfg(feature = "anyhow")))]
     #[doc(inline)]
     pub use sentry_anyhow as anyhow;
     #[cfg(feature = "backtrace")]
+    #[cfg_attr(doc_cfg, doc(cfg(feature = "backtrace")))]
     #[doc(inline)]
     pub use sentry_backtrace as backtrace;
     #[cfg(feature = "contexts")]
+    #[cfg_attr(doc_cfg, doc(cfg(feature = "contexts")))]
     #[doc(inline)]
     pub use sentry_contexts as contexts;
     #[cfg(feature = "debug-images")]
+    #[cfg_attr(doc_cfg, doc(cfg(feature = "debug_images")))]
     #[doc(inline)]
     pub use sentry_debug_images as debug_images;
     #[cfg(feature = "log")]
+    #[cfg_attr(doc_cfg, doc(cfg(feature = "log")))]
     #[doc(inline)]
     pub use sentry_log as log;
     #[cfg(feature = "panic")]
+    #[cfg_attr(doc_cfg, doc(cfg(feature = "panic")))]
     #[doc(inline)]
     pub use sentry_panic as panic;
     #[cfg(feature = "slog")]
+    #[cfg_attr(doc_cfg, doc(cfg(feature = "slog")))]
     #[doc(inline)]
     pub use sentry_slog as slog;
     #[cfg(feature = "tracing")]
+    #[cfg_attr(doc_cfg, doc(cfg(feature = "tracing")))]
     #[doc(inline)]
     pub use sentry_tracing as tracing;
 }

sentry/src/transports/curl.rs

@@ -9,7 +9,10 @@ use crate::{sentry_debug, types::Scheme, ClientOptions, Envelope, Transport};
 
 /// A [`Transport`] that sends events via the [`curl`] library.
 ///
-/// This is enabled by the `curl` flag.
+/// This is enabled by the `curl` feature flag.
+///
+/// [`curl`]: https://crates.io/crates/curl
+#[cfg_attr(doc_cfg, doc(cfg(feature = "curl")))]
 pub struct CurlHttpTransport {
     thread: TransportThread,
 }

sentry/src/transports/reqwest.rs

@@ -10,7 +10,10 @@ use crate::{sentry_debug, ClientOptions, Envelope, Transport};
 ///
 /// When the `transport` feature is enabled this will currently
 /// be the default transport.  This is separately enabled by the
-/// `reqwest` flag.
+/// `reqwest` feature flag.
+///
+/// [`reqwest`]: https://crates.io/crates/reqwest
+#[cfg_attr(doc_cfg, doc(cfg(feature = "reqwest")))]
 pub struct ReqwestHttpTransport {
     thread: TransportThread,
 }

sentry/src/transports/surf.rs

@@ -8,7 +8,10 @@ use crate::{sentry_debug, ClientOptions, Envelope, Transport};
 
 /// A [`Transport`] that sends events via the [`surf`] library.
 ///
-/// This is enabled by the `surf` flag.
+/// This is enabled by the `surf` feature flag.
+///
+/// [`surf`]: https://crates.io/crates/surf
+#[cfg_attr(doc_cfg, doc(cfg(feature = "surf")))]
 pub struct SurfHttpTransport {
     thread: TransportThread,
 }