Require documentation on public interfaces

Previously, compiling would not warn or error for lack of documentation.
Now the compiler will fail if public interfaces are left without
documentation. To prevent the library from failing, all public
interfaces have been documented.

resolves #72

proto/eraftpb.proto

@@ -6,6 +6,16 @@ enum EntryType {
     EntryConfChange = 1;
 }
 
+// The entry is a type of change that needs to be applied. It contains two data fields.
+// Which field is used and how can be determined by the entry type.
+//
+// For normal entries, the data field should contain the data change that should be applied.
+// The context field can be used for any contextual data that might be relevant to the
+// application of the data.
+//
+// For configuration changes, the data will contain the ConfChange message and the
+// context will provide anything needed to assist the configuration change. The context
+// if for the user to set and use in this case.
 message Entry {
     EntryType entry_type = 1;
     uint64 term = 2;

src/errors.rs

@@ -17,30 +17,38 @@ use std::{cmp, io, result};
 use protobuf::ProtobufError;
 
 quick_error! {
+    /// The base error type for raft
     #[derive(Debug)]
     pub enum Error {
+        /// An IO error occurred
         Io(err: io::Error) {
             from()
             cause(err)
             description(err.description())
         }
+        /// A storage error occurred.
         Store(err: StorageError) {
             from()
             cause(err)
             description(err.description())
         }
+        /// Raft cannot step the local message.
         StepLocalMsg {
             description("raft: cannot step raft local message")
         }
+        /// The raft peer is not found and thus cannot step.
         StepPeerNotFound {
             description("raft: cannot step as peer not found")
         }
+        /// The proposal of changes was dropped.
         ProposalDropped {
             description("raft: proposal dropped")
         }
+        /// The configuration is invalid.
         ConfigInvalid(desc: String) {
             description(desc)
         }
+        /// A Protobuf message failed in some manner.
         Codec(err: ProtobufError) {
             from()
             cause(err)
@@ -67,20 +75,26 @@ impl cmp::PartialEq for Error {
 }
 
 quick_error! {
+    /// An error with the storage.
     #[derive(Debug)]
     pub enum StorageError {
+        /// The storage was compacted and not accessible
         Compacted {
             description("log compacted")
         }
+        /// The log is not available.
         Unavailable {
             description("log unavailable")
         }
+        /// The snapshot is out of date.
         SnapshotOutOfDate {
             description("snapshot out of date")
         }
+        /// The snapshot is being created.
         SnapshotTemporarilyUnavailable {
             description("snapshot is temporarily unavailable")
         }
+        /// Some other error occurred.
         Other(err: Box<error::Error + Sync + Send>) {
             from()
             cause(err.as_ref())
@@ -106,6 +120,7 @@ impl cmp::PartialEq for StorageError {
     }
 }
 
+/// A result type that wraps up the raft errors.
 pub type Result<T> = result::Result<T, Error>;
 
 #[cfg(test)]

src/lib.rs

@@ -215,6 +215,7 @@ For more information, check out an [example](examples/single_mem_node/main.rs#L1
 #![cfg_attr(feature = "dev", feature(plugin))]
 #![cfg_attr(feature = "dev", plugin(clippy))]
 #![cfg_attr(not(feature = "dev"), allow(unknown_lints))]
+#![deny(missing_docs)]
 
 extern crate fxhash;
 #[macro_use]
@@ -224,6 +225,8 @@ extern crate protobuf;
 extern crate quick_error;
 extern crate rand;
 
+/// This module supplies the needed message types. However, it is autogenerated and thus cannot be
+/// documented by field.
 pub mod eraftpb;
 mod errors;
 mod log_unstable;

src/log_unstable.rs

@@ -1,3 +1,5 @@
+//! A representation of not-yet-committed log entries and state.
+
 // Copyright 2016 PingCAP, Inc.
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
@@ -27,22 +29,27 @@
 
 use eraftpb::{Entry, Snapshot};
 
-// unstable.entries[i] has raft log position i+unstable.offset.
-// Note that unstable.offset may be less than the highest log
-// position in storage; this means that the next write to storage
-// might need to truncate the log before persisting unstable.entries.
+/// unstable.entries[i] has raft log position i+unstable.offset.
+/// Note that unstable.offset may be less than the highest log
+/// position in storage; this means that the next write to storage
+/// might need to truncate the log before persisting unstable.entries.
 #[derive(Debug, PartialEq, Default)]
 pub struct Unstable {
-    // the incoming unstable snapshot, if any.
+    /// the incoming unstable snapshot, if any.
     pub snapshot: Option<Snapshot>,
-    // all entries that have not yet been written to storage.
+
+    /// all entries that have not yet been written to storage.
     pub entries: Vec<Entry>,
+
+    /// The offset from the vector index.
     pub offset: u64,
 
+    /// The tag to use when logging.
     pub tag: String,
 }
 
 impl Unstable {
+    /// Creates a new log of unstable entries.
     pub fn new(offset: u64, tag: String) -> Unstable {
         Unstable {
             offset,
@@ -51,16 +58,17 @@ impl Unstable {
             tag,
         }
     }
-    // maybe_first_index returns the index of the first possible entry in entries
-    // if it has a snapshot.
+
+    /// maybe_first_index returns the index of the first possible entry in entries
+    /// if it has a snapshot.
     pub fn maybe_first_index(&self) -> Option<u64> {
         self.snapshot
             .as_ref()
             .map(|snap| snap.get_metadata().get_index() + 1)
     }
 
-    // maybe_last_index returns the last index if it has at least one
-    // unstable entry or snapshot.
+    /// maybe_last_index returns the last index if it has at least one
+    /// unstable entry or snapshot.
     pub fn maybe_last_index(&self) -> Option<u64> {
         match self.entries.len() {
             0 => self.snapshot
@@ -70,8 +78,8 @@ impl Unstable {
         }
     }
 
-    // maybe_term returns the term of the entry at index idx, if there
-    // is any.
+    /// maybe_term returns the term of the entry at index idx, if there
+    /// is any.
     pub fn maybe_term(&self, idx: u64) -> Option<u64> {
         if idx < self.offset {
             let snapshot = self.snapshot.as_ref()?;
@@ -91,6 +99,8 @@ impl Unstable {
         }
     }
 
+    /// Moves the stable offset up to the index. Provided that the index
+    /// is in the same election term.
     pub fn stable_to(&mut self, idx: u64, term: u64) {
         let t = self.maybe_term(idx);
         if t.is_none() {
@@ -104,6 +114,7 @@ impl Unstable {
         }
     }
 
+    /// Removes the snapshot from self if the index of the snapshot matches
     pub fn stable_snap_to(&mut self, idx: u64) {
         if self.snapshot.is_none() {
             return;
@@ -113,13 +124,14 @@ impl Unstable {
         }
     }
 
+    /// From a given snapshot, restores the snapshot to self, but doesn't unpack.
     pub fn restore(&mut self, snap: Snapshot) {
         self.entries.clear();
         self.offset = snap.get_metadata().get_index() + 1;
         self.snapshot = Some(snap);
     }
 
-    // append entries to unstable, truncate local block first if overlapped.
+    /// append entries to unstable, truncate local block first if overlapped.
     pub fn truncate_and_append(&mut self, ents: &[Entry]) {
         let after = ents[0].get_index();
         if after == self.offset + self.entries.len() as u64 {
@@ -140,6 +152,12 @@ impl Unstable {
         }
     }
 
+    /// Returns a slice of entries between the high and low.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the lo or hi are out of bounds.
+    /// Panics if lo > hi.
     pub fn slice(&self, lo: u64, hi: u64) -> &[Entry] {
         self.must_check_outofbounds(lo, hi);
         let l = lo as usize;
@@ -148,6 +166,8 @@ impl Unstable {
         &self.entries[l - off..h - off]
     }
 
+    /// Asserts the hi and lo values against each other and against the
+    /// entries themselves.
     pub fn must_check_outofbounds(&self, lo: u64, hi: u64) {
         if lo > hi {
             panic!("{} invalid unstable.slice {} > {}", self.tag, lo, hi)