From 72a24ad023a318909c32251b972067edf8bdc5c6 Mon Sep 17 00:00:00 2001
From: Gav Wood <i@gavwood.com>
Date: Sun, 20 Dec 2015 12:28:13 +0000
Subject: [PATCH] SemanticVersion struct. Additional documentation.

---
 src/lib.rs              |  1 +
 src/semantic_version.rs | 28 ++++++++++++++++++++++++++++
 src/trie/journal.rs     |  4 ++++
 3 files changed, 33 insertions(+)
 create mode 100644 src/semantic_version.rs

diff --git a/src/lib.rs b/src/lib.rs
index 9120f0977..4859a8580 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -66,5 +66,6 @@ pub mod trie;
 pub mod nibbleslice;
 pub mod heapsizeof;
 pub mod squeeze;
+pub mod semantic_version;
 
 //pub mod network;
diff --git a/src/semantic_version.rs b/src/semantic_version.rs
new file mode 100644
index 000000000..026902263
--- /dev/null
+++ b/src/semantic_version.rs
@@ -0,0 +1,28 @@
+/// A version value with strict meaning. Use `to_u32` to convert to a simple integer.
+/// 
+/// # Example
+/// ```
+/// extern crate ethcore;
+/// use ethcore::engine::*;
+/// fn main() {
+///   assert_eq!(SemanticVersion::new(1, 2, 3).as_u32(), 0x010203);
+/// }
+/// ```
+pub struct SemanticVersion {
+	/// Major version - API/feature removals & breaking changes.
+	pub major: u8,
+	/// Minor version - API/feature additions.
+	pub minor: u8,
+	/// Tiny version - bug fixes.
+	pub tiny: u8,
+}
+
+impl SemanticVersion {
+	/// Create a new object.
+	pub fn new(major: u8, minor: u8, tiny: u8) -> SemanticVersion { SemanticVersion{major: major, minor: minor, tiny: tiny} }
+
+	/// Convert to a `u32` representation.
+	pub fn as_u32(&self) -> u32 { ((self.major as u32) << 16) + ((self.minor as u32) << 8) + self.tiny as u32 }
+}
+
+// TODO: implement Eq, Comparison and Debug/Display for SemanticVersion.
diff --git a/src/trie/journal.rs b/src/trie/journal.rs
index 77efc991c..948f07a06 100644
--- a/src/trie/journal.rs
+++ b/src/trie/journal.rs
@@ -11,8 +11,11 @@ enum Operation {
 	Delete(H256),
 }
 
+/// How many insertions and removals were done in an `apply` operation.
 pub struct Score {
+	/// Number of insertions.
 	pub inserts: usize,
+	/// Number of removals.
 	pub removes: usize,
 }
 
@@ -54,6 +57,7 @@ impl Journal {
 		}
 	}
 
+	/// Apply this journal to the HashDB `db` and return the number of insertions and removals done.
 	pub fn apply(self, db: &mut HashDB) -> Score {
 		trace!("applying {:?} changes", self.0.len());
 		let mut ret = Score{inserts: 0, removes: 0};