Merge pull request #95 from jackson-sandland/source-documentation-review

94: source doc review

src/accountant.rs

@@ -1,6 +1,6 @@
-//! The Accountant tracks client balances and the progress of pending
+//! The `accountant` module tracks client balances, and the progress of pending
 //! transactions. It offers a high-level public API that signs transactions
-//! on behalf of the caller and a private low-level API for when they have
+//! on behalf of the caller, and a private low-level API for when they have
 //! already been signed and verified.
 
 use chrono::prelude::*;

src/accountant_skel.rs

@@ -1,6 +1,6 @@
-//! The AccountantSkel is a microservice that exposes the high-level
+//! The `accountant_skel` module is a microservice that exposes the high-level
 //! Accountant API to the network. Its message encoding is currently
-//! in flux. Clients should AccountantStub to interact with it.
+//! in flux. Clients should use AccountantStub to interact with it.
 
 use accountant::Accountant;
 use bincode::{deserialize, serialize};

src/accountant_stub.rs

@@ -1,4 +1,4 @@
-//! A AccountantStub is client-side object that interfaces with a server-side Accountant
+//! The `accountant_stub` module is a client-side object that interfaces with a server-side Accountant
 //! object via the network interface exposed by AccountantSkel. Client code should use
 //! this object instead of writing messages to the network directly. The binary
 //! encoding of its messages are unstable and may change in future releases.

src/entry.rs

@@ -1,6 +1,6 @@
-//! An Entry is a fundamental building block of Proof of History. It contains a
-//! unqiue ID that is the hash of the Entry before it plus the hash of the
-//! transactins within it. Entries cannot be reordered and its field `num_hashes`
+//! The `entry` module is a fundamental building block of Proof of History. It contains a
+//! unique ID that is the hash of the Entry before it, plus the hash of the
+//! transactions within it. Entries cannot be reordered, and its field `num_hashes`
 //! represents an approximate amount of time since the last Entry was created.
 use event::Event;
 use hash::{extend_and_hash, hash, Hash};

src/event.rs

@@ -1,4 +1,4 @@
-//! An Event may be a Transaction or a Witness used to process a pending
+//! The `event` module handles events, which may be a `Transaction`, or a `Witness` used to process a pending
 //! Transaction.
 
 use bincode::serialize;

src/hash.rs

@@ -1,4 +1,4 @@
-//! A module for creating SHA-256 hashes.
+//! The `hash` module provides functions for creating SHA-256 hashes.
 
 use generic_array::GenericArray;
 use generic_array::typenum::U32;

src/historian.rs

@@ -1,4 +1,4 @@
-//! The Historian provides a microservice for generating a Proof of History.
+//! The `historian` module provides a microservice for generating a Proof of History.
 //! It manages a thread containing a Proof of History Recorder.
 
 use entry::Entry;

src/ledger.rs

@@ -1,4 +1,4 @@
-//! The `ledger` module provides the functions for parallel verification of the
+//! The `ledger` module provides functions for parallel verification of the
 //! Proof of History ledger.
 
 use entry::{next_tick, Entry};

src/mint.rs

@@ -1,4 +1,4 @@
-//! A library for generating the chain's genesis block.
+//! The `mint` module is a library for generating the chain's genesis block.
 
 use entry::Entry;
 use entry::create_entry;

src/plan.rs

@@ -1,4 +1,4 @@
-//! A domain-specific language for payment plans. Users create Plan objects that
+//! The `plan` module provides a domain-specific language for payment plans. Users create Plan objects that
 //! are given to an interpreter. The interpreter listens for `Witness` events,
 //! which it uses to reduce the payment plan. When the plan is reduced to a
 //! `Payment`, the payment is executed.

src/recorder.rs

@@ -1,7 +1,7 @@
 //! The `recorder` module provides an object for generating a Proof of History.
 //! It records Event items on behalf of its users. It continuously generates
 //! new hashes, only stopping to check if it has been sent an Event item. It
-//! tags each Event with an Entry and sends it back. The Entry includes the
+//! tags each Event with an Entry, and sends it back. The Entry includes the
 //! Event, the latest hash, and the number of hashes since the last event.
 //! The resulting stream of entries represents ordered events in time.
 

src/result.rs

@@ -1,4 +1,4 @@
-//! Exposes a Result type that propagates one of many different Error types.
+//! The `result` module exposes a Result type that propagates one of many different Error types.
 
 use bincode;
 use serde_json;

src/signature.rs

@@ -1,4 +1,4 @@
-//! The `signature` module provides functionality for public and private keys
+//! The `signature` module provides functionality for public, and private keys.
 
 use generic_array::GenericArray;
 use generic_array::typenum::{U32, U64};

src/streamer.rs

@@ -1,4 +1,4 @@
-//! A module for efficient batch processing of UDP packets.
+//! The 'streamer` module allows for efficient batch processing of UDP packets.
 
 use result::{Error, Result};
 use std::fmt;