From c808ffc21aa2711f8df76e8013dab36fd9e86dfd Mon Sep 17 00:00:00 2001
From: Cheng XU <git@xuc.me>
Date: Thu, 5 Dec 2019 21:09:03 +0800
Subject: [PATCH] add README, more doc

---
 Cargo.toml       |  2 ++
 README.md        | 50 ++++++++++++++++++++++++++++++++++++++++++++++++
 src/clock/mod.rs |  2 +-
 src/lib.rs       | 39 +++++++++++++++++++++++++++++++++++++
 src/timer.rs     |  2 +-
 src/types.rs     |  3 +++
 6 files changed, 96 insertions(+), 2 deletions(-)

diff --git a/Cargo.toml b/Cargo.toml
index 23e7202..9b5570b 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -5,7 +5,9 @@ authors = ["Cheng XU <rust@xuc.me>"]
 edition = "2018"
 build = "build.rs"
 license = "MIT OR Apache-2.0"
+description = "Measure how long it takes for a program to execute in different clocks"
 repository = "https://github.com/xu-cheng/howlong"
+documentation = "https://docs.rs/howlong"
 readme = "README.md"
 
 [dependencies]
diff --git a/README.md b/README.md
index 0e38633..ed6cd79 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,51 @@
 # howlong
+
+This crate allows you to measure how long it takes for a program to execute in different clocks. It ports the functions of the [`boost-chrono`](https://boost.org/libs/chrono) and [`boost-timer`](https://boost.org/libs/timer) libraries.
+
+The following clocks and their corresponding timers are implemented.
+
+* `SystemClock`, `SystemTimer`
+* `SteadyClock`, `SteadyTimer` if supported by the system.
+* `HighResolutionClock`, `HighResolutionTimer`
+* `ProcessRealCPUClock`, `ProcessRealCPUTimer`
+* `ProcessUserCPUClock`, `ProcessUserCPUTimer`
+* `ProcessSystemCPUClock`, `ProcessSystemCPUTimer`
+* `ProcessCPUClock`, `ProcessCPUTimer`
+* `ThreadClock`, `ThreadTimer`
+
+## Documentation
+
+<https://doc.rs/howlong>
+
+## Usage
+
+Add this to your `Cargo.toml`:
+
+```toml
+[dependencies]
+howlong = "0.1"
+```
+
+## Examples
+
+```rust
+use howlong::*;
+
+let timer = HighResolutionTimer::new();
+// do some computations
+println!("{:?} have passed.", timer.elapsed());
+
+let timer = ProcessCPUTimer::new();
+// do other computations
+println!("{}", timer.elapsed());
+```
+
+## License
+
+<sup>
+Licensed under either of <a href="LICENSE-APACHE">Apache License, Version 2.0</a> or <a href="LICENSE-MIT">MIT license</a> at your option.
+</sup>
+<br>
+<sub>
+Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
+</sub>
diff --git a/src/clock/mod.rs b/src/clock/mod.rs
index eca7c3a..2d31725 100644
--- a/src/clock/mod.rs
+++ b/src/clock/mod.rs
@@ -21,7 +21,7 @@
 //! # Implementations
 //!
 //! The Implementations of the clocks are based on
-//! [`boost-chrono` library](http://boost.org/libs/chrono)
+//! [`boost-chrono` library](https://boost.org/libs/chrono).
 //! The following table listes the underlying APIs for different clocks.
 //!
 //! | Clock | Posix | Darwin | Windows |
diff --git a/src/lib.rs b/src/lib.rs
index 85776ce..5cfc368 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,3 +1,42 @@
+//! This crate allows you to measure how long it takes for a program to execute in different
+//! clocks. It ports the functions of the [`boost-chrono`](https://boost.org/libs/chrono)
+//! and [`boost-timer`](https://boost.org/libs/timer) libraries.
+//!
+//! The following clocks and their corresponding timers are implemented.
+//!
+//! * [`SystemClock`], [`SystemTimer`]
+//! * [`SteadyClock`], [`SteadyTimer`] if supported by the system.
+//! * [`HighResolutionClock`], [`HighResolutionTimer`]
+//! * [`ProcessRealCPUClock`], [`ProcessRealCPUTimer`]
+//! * [`ProcessUserCPUClock`], [`ProcessUserCPUTimer`]
+//! * [`ProcessSystemCPUClock`], [`ProcessSystemCPUTimer`]
+//! * [`ProcessCPUClock`], [`ProcessCPUTimer`]
+//! * [`ThreadClock`], [`ThreadTimer`]
+//!
+//! See [`crate::clock`] to read more about their differences.
+//!
+//! # Usage
+//!
+//! Add this to your `Cargo.toml`:
+//! ```toml
+//! [dependencies]
+//! howlong = "0.1"
+//! ```
+//!
+//! # Examples
+//!
+//! ```
+//! use howlong::*;
+//!
+//! let timer = HighResolutionTimer::new();
+//! // do some computations
+//! println!("{:?} have passed.", timer.elapsed());
+//!
+//! let timer = ProcessCPUTimer::new();
+//! // do other computations
+//! println!("{}", timer.elapsed());
+//! ```
+
 mod types;
 pub use types::*;
 
diff --git a/src/timer.rs b/src/timer.rs
index a394767..9fb10fd 100644
--- a/src/timer.rs
+++ b/src/timer.rs
@@ -1,7 +1,7 @@
 //! Measure how long a program takes to execute.
 //!
 //! A varity of timers are implemented using different clocks.
-//! See [`crate::clock`] to read more about their difference.
+//! See [`crate::clock`] to read more about their differences.
 //!
 //! # Examples
 //!
diff --git a/src/types.rs b/src/types.rs
index f1538d9..3b29b30 100644
--- a/src/types.rs
+++ b/src/types.rs
@@ -85,8 +85,11 @@ impl Into<ProcessDuration> for ProcessTimePoint {
 /// Like [`Duration`] but captures real, user-CPU, and system-CPU process times.
 #[derive(Clone, Copy, Debug, Default)]
 pub struct ProcessDuration {
+    /// [`Duration`] measured by wall-time clock.
     pub real: Duration,
+    /// [`Duration`] measured by user-CPU clock.
     pub user: Duration,
+    /// [`Duration`] measured by system-CPU clock.
     pub system: Duration,
 }