Better docs for entry

src/entry.rs

@@ -9,18 +9,29 @@ use transaction::Transaction;
 /// Each Entry contains three pieces of data. The `num_hashes` field is the number
 /// of hashes performed since the previous entry.  The `id` field is the result
 /// of hashing `id` from the previous entry `num_hashes` times.  The `transactions`
-/// field points to Transactions that took place shortly after `id` was generated.
+/// field points to Transactions that took place shortly before `id` was generated.
 ///
 /// If you divide `num_hashes` by the amount of time it takes to generate a new hash, you
 /// get a duration estimate since the last Entry. Since processing power increases
 /// over time, one should expect the duration `num_hashes` represents to decrease proportionally.
-/// Though processing power varies across nodes, the network gives priority to the
+/// An upper bound on Duration can be estimated by assuming each hash was generated by the
-/// fastest processor. Duration should therefore be estimated by assuming that the hash
+/// world's fastest processor at the time the entry was recorded. Or said another way, it
-/// was generated by the fastest processor at the time the entry was recorded.
+/// is physically not possible for a shorter duration to have occurred if one assumes the
+/// hash was computed by the world's fastest processor at that time. The hash chain is both
+/// a Verifiable Delay Function (VDF) and a Proof of Work (not to be confused with Proof or
+/// Work consensus!)
+
 #[derive(Serialize, Deserialize, Debug, PartialEq, Eq, Clone)]
 pub struct Entry {
+    /// The number of hashes since the previous Entry ID.
     pub num_hashes: u64,
+
+    /// The SHA-256 hash `num_hashes` after the previous Entry ID.
     pub id: Hash,
+
+    /// An unordered list of transactions that were observed before the Entry ID was
+    /// generated. The may have been observed before a previous Entry ID but were
+    /// pushed back into this list to ensure deterministic interpretation of the ledger.
     pub transactions: Vec<Transaction>,
 }