docs: Provide more upfront info on features and integrations, nitpicky fixes

sentry-contexts/src/integration.rs

@@ -8,8 +8,19 @@ use crate::utils::{device_context, os_context, rust_context, server_name};
 
 /// Adds Contexts to Sentry Events.
 ///
+/// This integration is enabled by default in `sentry` and adds `device`, `os`
+/// and `rust` contexts to Events, and also sets a `server_name` if it is not
+/// already defined.
+///
 /// See the [Contexts Interface] documentation for more info.
 ///
+/// # Examples
+///
+/// ```rust
+/// let integration = sentry_contexts::ContextIntegration::new().add_os(false);
+/// let _sentry = sentry::init(sentry::ClientOptions::new().add_integration(integration));
+/// ```
+///
 /// [Contexts Interface]: https://develop.sentry.dev/sdk/event-payloads/contexts/
 #[derive(Debug)]
 pub struct ContextIntegration {

sentry-contexts/src/lib.rs

@@ -1,14 +1,14 @@
-//! Adds Contexts to Sentry Events
+//! Adds Contexts to Sentry Events.
 //!
 //! This integration is enabled by default in `sentry` and adds `device`, `os`
-//! and `rust` contexts to Events, as well as sets a `server_name` if not
+//! and `rust` contexts to Events, and also sets a `server_name` if it is not
 //! already defined.
 //!
 //! See the [Contexts Interface] documentation for more info.
 //!
 //! # Examples
 //!
-//! ```
+//! ```rust
 //! let integration = sentry_contexts::ContextIntegration::new().add_os(false);
 //! let _sentry = sentry::init(sentry::ClientOptions::new().add_integration(integration));
 //! ```

sentry-core/src/lib.rs

@@ -1,11 +1,11 @@
-//! This crate provides the core of the [Sentry](https://sentry.io/) SDK, which
-//! can be used to log events and errors.
+//! This crate provides the core of the [Sentry] SDK, which can be used to log
+//! events and errors.
 //!
-//! This crate is meant for integration authors and third party library authors
+//! `sentry-core` is meant for integration authors and third-party library authors
 //! that want to instrument their code for sentry.
 //!
 //! Regular users who wish to integrate sentry into their applications should
-//! rather use the [`sentry`] crate, which comes with a default transport, and
+//! instead use the [`sentry`] crate, which comes with a default transport and
 //! a large set of integrations for various third-party libraries.
 //!
 //! # Core Concepts
@@ -26,15 +26,16 @@
 //!
 //! # Features
 //!
-//! * `feature = "client"`: Activates the [`Client`] type and certain
+//! - `feature = "client"`: Activates the [`Client`] type and certain
 //!   [`Hub`] functionality.
-//! * `feature = "test"`: Activates the [`test`] module, which can be used to
+//! - `feature = "test"`: Activates the [`test`] module, which can be used to
 //!   write integration tests. It comes with a test transport which can capture
 //!   all sent events for inspection.
-//! * `feature = "debug-logs"`: Uses the `log` crate for debug output, instead
+//! - `feature = "debug-logs"`: Uses the `log` crate for debug output, instead
 //!   of printing to `stderr`. This feature is **deprecated** and will be
 //!   replaced by a dedicated log callback in the future.
 //!
+//! [Sentry]: https://sentry.io/
 //! [`sentry`]: https://crates.io/crates/sentry
 //! [Unified API]: https://develop.sentry.dev/sdk/unified-api/
 //! [`Client`]: struct.Client.html

sentry-debug-images/src/lib.rs

@@ -1,17 +1,17 @@
-//! The Sentry Debug Images Integration.
+//! The Sentry Debug Images integration.
 //!
 //! The [`DebugImagesIntegration`] adds metadata about the loaded shared
 //! libraries to Sentry [`Event`]s.
 //!
-//! This Integration only works on Unix-like OSs right now. Support for Windows
+//! This Integration only works on Unix-like OSes right now. Support for Windows
 //! will be added in the future.
 //!
 //! # Configuration
 //!
 //! The integration by default attaches this information to all [`Event`]s, but
 //! a custom filter can be defined as well.
 //!
-//! ```
+//! ```rust
 //! use sentry_core::Level;
 //! let integration = sentry_debug_images::DebugImagesIntegration::new()
 //!     .filter(|event| event.level >= Level::Warning);

sentry-log/src/lib.rs

@@ -2,7 +2,7 @@
 //!
 //! The `log` crate is supported in two ways. First, logs can be captured as
 //! breadcrumbs for later. Secondly, error logs can be captured as events to
-//! Sentry. By default anything above `Info` is recorded as breadcrumb and
+//! Sentry. By default anything above `Info` is recorded as a breadcrumb and
 //! anything above `Error` is captured as error event.
 //!
 //! # Examples

sentry-panic/src/lib.rs

@@ -1,4 +1,4 @@
-//! The Sentry Panic handler Integration.
+//! The Sentry Panic handler integration.
 //!
 //! The `PanicIntegration`, which is enabled by default in `sentry`, installs a
 //! panic handler that will automatically dispatch all errors to Sentry that

sentry/src/lib.rs

@@ -1,38 +1,49 @@
 //! This crate provides support for logging events and errors / panics to the
-//! [Sentry](https://sentry.io/) error logging service.  It integrates with the standard panic
+//! [Sentry] error logging service. It integrates with the standard panic
 //! system in Rust as well as a few popular error handling setups.
 //!
+//! [Sentry]: https://sentry.io/
+//!
 //! # Quickstart
 //!
-//! The most convenient way to use this library is the [`sentry::init`] function,
+//! The most convenient way to use this library is via the [`sentry::init`] function,
 //! which starts a sentry client with a default set of integrations, and binds
 //! it to the current [`Hub`].
 //!
 //! The [`sentry::init`] function returns a guard that when dropped will flush Events that were not
-//! yet sent to the sentry service.  It has a two second deadline for this so shutdown of
-//! applications might slightly delay as a result of this.  Keep the guard around or sending events
+//! yet sent to the sentry service. It has a two second deadline for this so shutdown of
+//! applications might slightly delay as a result of this. Keep the guard around or sending events
 //! will not work.
 //!
-//! ```
+//! ```rust
 //! let _guard = sentry::init("https://key@sentry.io/42");
 //! sentry::capture_message("Hello World!", sentry::Level::Info);
 //! // when the guard goes out of scope here, the client will wait up to two
 //! // seconds to send remaining events to the service.
 //! ```
 //!
+//! More complex examples on how to use sentry can also be found in [examples]. Extended instructions
+//! may also be found on [Sentry itself].
+//!
 //! [`sentry::init`]: fn.init.html
 //! [`Hub`]: struct.Hub.html
+//! [examples]: https://github.com/getsentry/sentry-rust/tree/master/sentry/examples
+//! [Sentry itself]: https://docs.sentry.io/platforms/rust
 //!
 //! # Integrations
 //!
-//! What makes this crate useful are the various integrations that exist.  Some of them are enabled
-//! by default, some uncommon ones or for deprecated parts of the ecosystem a feature flag needs to
-//! be enabled.  For the available integrations and how to use them see
-//! [integrations](integrations/index.html) and [apply_defaults](fn.apply_defaults.html).
+//! What makes this crate useful are its various integrations. Some of them are enabled by
+//! default; See [Features]. Uncommon integrations or integrations for deprecated parts of
+//! the ecosystem require a feature flag. For available integrations and how to use them, see
+//! [integrations] and [apply_defaults].
+//!
+//! [Features]: #features
+//! [integrations]: integrations/index.html
+//! [apply_defaults]: fn.apply_defaults.html
 //!
 //! # Minimal API
 //!
-//! This crate comes fully featured. If the goal is to instrument libraries for usage
+//! This crate comes fully-featured. If the goal is to instrument libraries for usage
 //! with sentry, or to extend sentry with a custom [`Integration`] or a [`Transport`],
 //! one should use the [`sentry-core`] crate instead.
 //!
@@ -42,34 +53,54 @@
 //!
 //! # Features
 //!
-//! Functionality of the crate can be turned on and off by feature flags.  This is the current list
-//! of feature flags:
-//!
-//! Default features:
-//!
-//! * `backtrace`: Enables backtrace support.
-//! * `contexts`: Enables capturing device, os, and rust contexts.
-//! * `panic`: Enables support for capturing panics.
-//! * `transport`: Enables the default transport, which is currently `reqwest` with `native-tls`.
-//!
-//! Additional features:
-//!
-//! * `anyhow`: Enables support for the `anyhow` crate.
-//! * `debug-images`: Attaches a list of loaded libraries to events (currently only supported on unix).
-//! * `log`: Enables support for the `log` and `env_logger` crate.
-//! * `slog`: Enables support for the `slog` crate.
-//! * `tracing`: Enables support for the `tracing` crate.
-//! * `test`: Enables testing support.
-//! * `debug-logs`: Uses the `log` crate for internal logging.
-//! * `reqwest`: Enables the `reqwest` transport, which is currently the default.
-//! * `curl`: Enables the curl transport.
-//! * `surf`: Enables the surf transport.
-//! * `native-tls`: Uses the `native-tls` crate, which is currently the default.
-//!   This only has an effect on the `reqwest` transport.
-//! * `rustls`: Enables the `rustls` support of the `reqwest` transport.
-//!   Please note that `native-tls` is a default feature, and one needs to use
-//!   `default-features = false` to completely disable building `native-tls` dependencies.
-
+//! Additional functionality and integrations are enabled via feature flags. Some features require
+//! extra setup to function properly.
+//!
+//! | Feature        | Default | Is Integration | Deprecated | Additional notes                                                                         |
+//! | -------------- | ------- | -------------- | ---------- | ---------------------------------------------------------------------------------------- |
+//! | `backtrace`    | ✅      | 🔌             |            |                                                                                          |
+//! | `contexts`     | ✅      | 🔌             |            |                                                                                          |
+//! | `panic`        | ✅      | 🔌             |            |                                                                                          |
+//! | `transport`    | ✅      |                |            |                                                                                          |
+//! | `anyhow`       |         | 🔌             |            |                                                                                          |
+//! | `test`         |         |                |            |                                                                                          |
+//! | `debug-images` |         | 🔌             |            |                                                                                          |
+//! | `log`          |         | 🔌             |            | Requires extra setup; See [`sentry-log`]'s documentation.                               |
+//! | `debug-logs`   |         |                | ❗         | Requires extra setup; See [`sentry-log`]'s documentation.                               |
+//! | `slog`         |         | 🔌             |            | Requires extra setup; See [`sentry-slog`]'s documentation.                              |
+//! | `reqwest`      | ✅      |                |            |                                                                                          |
+//! | `native-tls`   | ✅      |                |            | `reqwest` must be enabled.                                                               |
+//! | `rustls`       |         |                |            | `reqwest` must be enabled. `native-tls` must be disabled via `default-features = false`. |
+//! | `curl`         |         |                |            |                                                                                          |
+//! | `surf`         |         |                |            |                                                                                          |
+//!
+//! [`sentry-log`]: https://crates.io/crates/sentry-log
+//! [`sentry-slog`]: https://crates.io/crates/sentry-slog
+//!
+//! ## Default features
+//! - `backtrace`: Enables backtrace support.
+//! - `contexts`: Enables capturing device, OS, and Rust contexts.
+//! - `panic`: Enables support for capturing panics.
+//! - `transport`: Enables the default transport, which is currently `reqwest` with `native-tls`.
+//!
+//! ## Debugging/Testing
+//! - `anyhow`: Enables support for the `anyhow` crate.
+//! - `test`: Enables testing support.
+//! - `debug-images`: Attaches a list of loaded libraries to events (currently only supported on Unix).
+//!
+//! ## Logging
+//! - `log`: Enables support for the `log` crate.
+//! - `slog`: Enables support for the `slog` crate.
+//! - `debug-logs`: **Deprecated**. Uses the `log` crate for internal logging.
+//!
+//! ## Transports
+//! - `reqwest`: **Default**. Enables the `reqwest` transport.
+//! - `native-tls`: **Default**. Uses the `native-tls` crate. This only affects the `reqwest` transport.
+//! - `rustls`: Enables `rustls` support for `reqwest`. Please note that `native-tls` is a default
+//!   feature, and `default-features = false` must be set to completely disable building `native-tls`
+//!   dependencies.
+//! - `curl`: Enables the curl transport.
+//! - `surf`: Enables the surf transport.
 #![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)]
@@ -89,28 +120,26 @@ pub use crate::init::{init, ClientInitGuard};
 /// Available Sentry Integrations.
 ///
 /// Integrations extend the functionality of the SDK for some common frameworks and
-/// libraries.  Integrations come two primary kinds: as event *sources* or as event
-/// *processors*.
+/// libraries. There are two different kinds of integrations:
+/// - Event sources
+/// - Event processors
 ///
-/// Integrations which are *sources*, like e.g. the
-/// [`sentry::integrations::anyhow`](integrations::anyhow) integration, usually provide one
-/// or more functions to create new events.  They will usually provide their own extension
-/// trait exposing a new method on the [`Hub`].
+/// Integrations which are **event sources** such as
+/// [`sentry::integrations::anyhow`] typically provide one or more functions to
+/// create new events. These integrations will have an extension trait which exposes
+/// a new method on the [`Hub`].
 ///
-/// Integrations which *process* events in some way usually implement the
-/// [`Itegration`](crate::Integration) trait and need to be installed when sentry is
-/// initialised.
+/// Integrations which **process events** in some way usually implement the
+/// [`Integration`] trait and need to be installed when sentry is initialised.
 ///
 /// # Installing Integrations
 ///
-/// Processing integrations which implement [`Integration`](crate::Integration) need to be
-/// installed when sentry is initialised.  This is done using the
-/// [`ClientOptions::add_integration`](crate::ClientOptions::add_integration) function, which you can
-/// use to add extra integrations.
+/// Processing integrations which implement [`Integration`] need to be installed
+/// when sentry is initialised. This can be accomplished by using
+/// [`ClientOptions::add_integration()`].
 ///
-/// For example if you disabled the default integrations (see below) but still wanted the
-/// [`sentry::integrations::debug_images`](integrations::debug_images) integration enabled,
-/// you could do this as such:
+/// For example, if one were to disable the default integrations (see below) but
+/// still wanted to use [`sentry::integrations::debug_images`]:
 ///
 /// ```
 /// # #[cfg(feature = "debug-images")] {
@@ -127,14 +156,19 @@ pub use crate::init::{init, ClientInitGuard};
 ///
 /// # Default Integrations
 ///
-/// The [`ClientOptions::default_integrations`](crate::ClientOptions::default_integrations)
-/// option is a boolean field that when enabled will enable a number of default integrations
-/// **before** any integrations provided by
-/// [`ClientOptions::integrations`](crate::ClientOptions::integrations) are installed.  This
-/// is done using the [`apply_defaults`] function, which should be consulted for more
-/// details and the list of which integrations are enabled by default.
+/// The [`ClientOptions::default_integrations`] option is a boolean field that
+/// when enabled will enable all of the default integrations via
+/// [`apply_defaults()`] **before** any integrations provided by
+/// [`ClientOptions::integrations`] are installed. Those interested in a list
+/// of default integrations and how they are applied are advised to visit
+/// [`apply_defaults()`]'s implementation.
 ///
-/// [`apply_defaults`]: ../fn.apply_defaults.html
+/// [`sentry::integrations::anyhow`]: integrations::anyhow
+/// [`Integration`]: crate::Integration
+/// [`ClientOptions::add_integration()`]: crate::ClientOptions::add_integration
+/// [`sentry::integrations::debug_images`]: integrations::debug_images
+/// [`ClientOptions::default_integrations`]: crate::ClientOptions::default_integrations
+/// [`apply_defaults()`]: ../fn.apply_defaults.html
 pub mod integrations {
     #[cfg(feature = "anyhow")]
     #[doc(inline)]