Recommend use of features to easily enable/disable profiling.

worr · Jan 5, 2022 · 0b4860b · 0b4860b
1 parent bea9288
commit 0b4860b
Show file tree

Hide file tree

Showing 2 changed files with 43 additions and 6 deletions.
diff --git a/examples/heap.rs b/examples/heap.rs
@@ -1,9  1,13 @@
-// This is a very simple example of how to do heap profiling of a program.
 // This is a very simple example of how to do heap profiling of a program. You
 // may want to create a feature called `dhat-heap` in your `Cargo.toml` and
 // uncomment the `#[cfg(feature = "dhat-heap")]` attributes.
 
 //#[cfg(feature = "dhat-heap")]
 #[global_allocator]
 static ALLOC: dhat::Alloc = dhat::Alloc;
 
 fn main() {
     //#[cfg(feature = "dhat-heap")]
     let _profiler = dhat::Profiler::new_heap();
 
     println!("Hello, world!");

diff --git a/src/lib.rs b/src/lib.rs
@@ -44,10  44,15 @@
 //! # Configuration (profiling and testing)
 //!
 //! In your `Cargo.toml` file, as well as specifying `dhat` as a dependency,
-//! you should enable source line debug info:
 //! you should (a) enable source line debug info, and (b) create a feature or
 //! two that lets you easily switch profiling on and off:
 //! ```toml
 //! [profile.release]
 //! debug = 1
 //!
 //! [features]
 //! dhat-heap = []    # if you are doing heap profiling
 //! dhat-ad-hoc = []  # if you are doing ad hoc profiling
 //! ```
 //! You should only use `dhat` in release builds. Debug builds are too slow to
 //! be useful.
@@ -57,15  62,28 @@
 //! For heap profiling, enable the global allocator by adding this code to your
 //! program:
 //! ```
 //! # // Tricky: comment out the `cfg` so it shows up in docs but the following
 //! # // line is still tsted by `cargo test`.
 //! # /*
 //! #[cfg(feature = "dhat-heap")]
 //! # */
 //! #[global_allocator]
 //! static ALLOC: dhat::Alloc = dhat::Alloc;
 //! ```
 //! Then add the following code to the very start of your `main` function:
 //! ```
 //! # // Tricky: comment out the `cfg` so it shows up in docs but the following
 //! # // line is still tsted by `cargo test`.
 //! # /*
 //! #[cfg(feature = "dhat-heap")]
 //! # */
 //! let _profiler = dhat::Profiler::new_heap();
 //! ```
-//! Profiling will occur during the lifetime of the [`Profiler`] instance.
-//!
 //! Then run this command to enable heap profiling during the lifetime of the
 //! [`Profiler`] instance:
 //! ```text
 //! cargo run --features dhat-heap
 //! ```
 //! [`dhat::Alloc`](Alloc) is slower than the normal allocator, so it should
 //! only be enabled while profiling.
 //!
@@ -79,12  97,27 @@
 //! To do this, add the following code to the very start of your `main`
 //! function:
 //!```
 //! # // Tricky: comment out the `cfg` so it shows up in docs but the following
 //! # // line is still tsted by `cargo test`.
 //! # /*
 //! #[cfg(feature = "dhat-ad-hoc")]
 //! # */
 //! let _profiler = dhat::Profiler::new_ad_hoc();
 //! ```
 //! Then insert calls like this at points of interest:
 //! ```
 //! # // Tricky: comment out the `cfg` so it shows up in docs but the following
 //! # // line is still tsted by `cargo test`.
 //! # /*
 //! #[cfg(feature = "dhat-ad-hoc")]
 //! # */
 //! dhat::ad_hoc_event(100);
 //! ```
 //! Then run this command to enable ad hoc profiling during the lifetime of the
 //! [`Profiler`] instance:
 //! ```text
 //! cargo run --features dhat-ad-hoc
 //! ```
 //! For example, imagine you have a hot function that is called from many call
 //! sites. You might want to know how often it is called and which other
 //! functions called it the most. In that case, you would add an
@@ -239,8  272,8 @@
 //! #[global_allocator]
 //! static ALLOC: dhat::Alloc = dhat::Alloc;
 //!
-//! # // Trickiness: `#[test]` is needed in a test, but messes things up here.
-//! # // So we comment it out in a way that will make it show up in the docs.
 //! # // Tricky: comment out the `#[test]` because it's needed in an actual
 //! # // test but messes up things here.
 //! # /*
 //! #[test]
 //! # */