Skip to content

Commit 3921338

Browse files
jan-auerjan-auer
committed
doc: Describe all feature flags in library docs
1 parent 57d2fb6 commit 3921338

File tree

1 file changed

+76
-71
lines changed

1 file changed

+76
-71
lines changed

‎src/lib.rs

Lines changed: 76 additions & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -4,24 +4,22 @@
44
//! style="width: 260px"></a>
55
//! </p>
66
//!
7-
//! This crate provides support for logging events and errors / panics to
8-
//! the [Sentry](https://sentry.io/) error logging service. It integrates with
9-
//! the standard panic system in Rust as well as a few popular error handling
10-
//! setups.
7+
//! This crate provides support for logging events and errors / panics to the
8+
//! [Sentry](https://sentry.io/) error logging service. It integrates with the standard panic
9+
//! system in Rust as well as a few popular error handling setups.
1110
//!
1211
//! # Quickstart
1312
//!
14-
//! To use the crate you need to create a client first. When a client is created
15-
//! it's typically bound to the current thread by calling `bind_client`. By default
16-
//! this happens by using the `sentry::init` convenience function. When the client
17-
//! is bound to the main thread it also becomes the default client for future
18-
//! threads created but it is always possible to override the client for a thread
19-
//! later by explicitly binding it.
13+
//! To use the crate you need to create a client first. When a client is created it's typically
14+
//! bound to the current thread by calling `bind_client`. By default this happens by using the
15+
//! `sentry::init` convenience function. When the client is bound to the main thread it also
16+
//! becomes the default client for future threads created but it is always possible to override the
17+
//! client for a thread later by explicitly binding it.
2018
//!
21-
//! The `sentry::init` function returns a guard that when dropped will flush
22-
//! Events that were not yet sent to the sentry service. It has a two second
23-
//! deadline for this so shutdown of applications might slightly delay as a result
24-
//! of this. Keep the guard around or sending events will not work.
19+
//! The `sentry::init` function returns a guard that when dropped will flush Events that were not
20+
//! yet sent to the sentry service. It has a two second deadline for this so shutdown of
21+
//! applications might slightly delay as a result of this. Keep the guard around or sending events
22+
//! will not work.
2523
//!
2624
//! ```
2725
//! let _guard = sentry::init("https://[email protected]/42");
@@ -32,78 +30,85 @@
3230
//!
3331
//! # Integrations
3432
//!
35-
//! What makes this crate useful are the various integrations that exist. Some
36-
//! of them are enabled by default, some uncommon ones or for deprecated parts of
37-
//! the ecosystem a feature flag needs to be enabled. For the available
38-
//! integrations and how to use them see [integrations](integrations/index.html).
33+
//! What makes this crate useful are the various integrations that exist. Some of them are enabled
34+
//! by default, some uncommon ones or for deprecated parts of the ecosystem a feature flag needs to
35+
//! be enabled. For the available integrations and how to use them see
36+
//! [integrations](integrations/index.html).
3937
//!
4038
//! # Scopes, Threads and Hubs
4139
//!
42-
//! Data is typically bound to a [`Scope`](struct.Scope.html). Scopes are stored
43-
//! in a hidden stack on a [`Hub`](struct.Hub.html). Once the library has been
44-
//! initialized a hub is automatically available. In the default config a new
45-
//! hub is created for each thread and they act independently.
40+
//! Data is typically bound to a [`Scope`](struct.Scope.html). Scopes are stored in a hidden stack
41+
//! on a [`Hub`](struct.Hub.html). Once the library has been initialized a hub is automatically
42+
//! available. In the default config a new hub is created for each thread and they act
43+
//! independently.
4644
//!
47-
//! The thread that calls `sentry::init` initializes the first hub which then automatically
48-
//! becomes the base of new hubs (You can get that hub by calling `Hub::main()`). If a
49-
//! new thread is spawned it gets a new hub based on that one (the thread calls
50-
//! `Hub::new_from_top(Hub::main())`). The current thread's hub is returned from
51-
//! `Hub::current()`. Any hub that is wrapped in an `Arc` can be temporarily bound to a
52-
//! thread with `Hub::run`. For more information see [`Hub`](struct.Hub.html).
45+
//! The thread that calls `sentry::init` initializes the first hub which then automatically becomes
46+
//! the base of new hubs (You can get that hub by calling `Hub::main()`). If a new thread is
47+
//! spawned it gets a new hub based on that one (the thread calls `Hub::new_from_top(Hub::main())`).
48+
//! The current thread's hub is returned from `Hub::current()`. Any hub that is wrapped in an `Arc`
49+
//! can be temporarily bound to a thread with `Hub::run`. For more information see
50+
//! [`Hub`](struct.Hub.html).
5351
//!
54-
//! Users are expected to reconfigure the scope with
55-
//! [`configure_scope`](fn.configure_scope.html). For more elaborate scope management
56-
//! the hub needs to be interfaced with directly.
52+
//! Users are expected to reconfigure the scope with [`configure_scope`](fn.configure_scope.html).
53+
//! For more elaborate scope management the hub needs to be interfaced with directly.
5754
//!
58-
//! In some situations (particularly in async code) it's often not possible to use
59-
//! the thread local hub. In that case a hub can be explicitly created and passed
60-
//! around. However due to the nature of some integrations some functionality like
61-
//! automatic breadcrumb recording depends on the thread local hub being correctly
62-
//! configured.
55+
//! In some situations (particularly in async code) it's often not possible to use the thread local
56+
//! hub. In that case a hub can be explicitly created and passed around. However due to the nature
57+
//! of some integrations some functionality like automatic breadcrumb recording depends on the
58+
//! thread local hub being correctly configured.
6359
//!
6460
//! # Minimal API
6561
//!
66-
//! This crate can also be used in "minimal" mode. This is enabled by disabling all
67-
//! default features of the crate. In that mode a minimal API set is retained that
68-
//! can be used to instrument code for Sentry without actually using Sentry. The
69-
//! minimal API is a small set of APIs that dispatch to the underlying implementations on
70-
//! the configured Sentry client. If the client is not there the minimal API will blackhole
71-
//! a lot of operations.
62+
//! This crate can also be used in "minimal" mode. This is enabled by disabling all default
63+
//! features of the crate. In that mode a minimal API set is retained that can be used to
64+
//! instrument code for Sentry without actually using Sentry. The minimal API is a small set of
65+
//! APIs that dispatch to the underlying implementations on the configured Sentry client. If the
66+
//! client is not there the minimal API will blackhole a lot of operations.
7267
//!
7368
//! Only if a user then also uses and configures Sentry this code becomes used.
7469
//!
75-
//! In minimal mode some types are restricted in functionality. For instance the
76-
//! `Client` is not available and the `Hub` does not retain all API functionality.
77-
//! To see what the APIs in mnimal mode look like you can build the docs for this
78-
//! crate without any features enabled.
70+
//! In minimal mode some types are restricted in functionality. For instance the `Client` is not
71+
//! available and the `Hub` does not retain all API functionality. To see what the APIs in mnimal
72+
//! mode look like you can build the docs for this crate without any features enabled.
7973
//!
8074
//! # Features
8175
//!
82-
//! Functionality of the crate can be turned on and off by feature flags. This is the
83-
//! current list of feature flags:
84-
//!
85-
//! default flags:
86-
//!
87-
//! * `with_client_implementation`: turns on the real client implementation.
88-
//! * `with_default_transport`: compiles in the default HTTP transport.
89-
//! * `with_backtrace`: enables backtrace support (automatically turned on in a few cases)
90-
//! * `with_panic`: enables the panic integration
91-
//! * `with_failure`: enables the `failure` integration
92-
//! * `with_log`: enables the `log` integration
93-
//! * `with_env_logger`: enables the `env_logger` integration
94-
//! * `with_device_info`: enables the device info context
95-
//! * `with_rust_info`: enables the rust compiler info context
96-
//! * `with_debug_meta`: enables debug meta support (permits server side symbolication)
97-
//! * `with_debug_to_log`: when enabled sentry will debug log to a debug log at all times
98-
//! instead of printing to stderr when debug is enabled on the hub.
99-
//!
100-
//! additional features:
101-
//!
102-
//! * `with_error_chain`: enables the error-chain integration
103-
//! * `with_test_support`: enables the test support module
104-
//! * `with_reqwest_transport`: enables the reqwest transport explicitly. This
105-
//! is currently the default transport.
106-
//! * `with_curl_transport`: enables the curl transport.
76+
//! Functionality of the crate can be turned on and off by feature flags. This is the current list
77+
//! of feature flags:
78+
//!
79+
//! Default features:
80+
//!
81+
//! * `with_client_implementation`: Turns on the real client implementation.
82+
//! * `with_default_transport`: Compiles in the default HTTP transport (see below).
83+
//! * `with_backtrace`: Enables backtrace support (automatically turned on in a few cases).
84+
//! * `with_panic`: Enables the panic integration.
85+
//! * `with_failure`: Enables the `failure` integration.
86+
//! * `with_device_info`: Enables the device info context.
87+
//! * `with_rust_info`: Enables the rust compiler info context instead of printing to stderr when
88+
//! debug is enabled on the hub.
89+
//!
90+
//! Additional context:
91+
//!
92+
//! * `with_debug_meta`: Adds debug meta to reported events (permits server side symbolication).
93+
//!
94+
//! Additional integrations:
95+
//!
96+
//! * `with_log`: Enables the `log` integration.
97+
//! * `with_env_logger`: Enables the `env_logger` integration.
98+
//! * `with_debug_to_log`: When enabled sentry will debug log to a debug log at all times.
99+
//! * `with_error_chain`: Enables the error-chain integration.
100+
//!
101+
//! Additional transports:
102+
//! * `with_reqwest_transport`: Enables the reqwest transport explicitly. This is currently the
103+
//! default transport.
104+
//! * `with_curl_transport`: Enables the curl transport.
105+
//! * `with_rustls`: Enables the `rustls` TLS implementation. This is currently the default when
106+
//! using the `with_reqwest_transport` feature.
107+
//! * `with_native_tls`: Enables the `default-tls` feature of the `reqwest` library.
108+
//!
109+
//! Testing:
110+
//!
111+
//! * `with_test_support`: Enables the test support module.
107112
#![warn(missing_docs)]
108113

109114
#[macro_use]

0 commit comments

Comments
 (0)