Resolved most clippy warnings 'doc_markdown'.

Author: niluxv

src/aes.rs

@@ -22,7 +22,7 @@ pub enum KeySize {
 }
 
 // aes in electronic codebook mode (ecb) encryption
-/// Get the best implementation of an EcbEncryptor
+/// Get the best implementation of an `EcbEncryptor`
 #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
 pub fn ecb_encryptor<X: PaddingProcessor + Send + 'static>(
         key_size: KeySize,
@@ -51,7 +51,7 @@ pub fn ecb_encryptor<X: PaddingProcessor + Send + 'static>(
     }
 }
 
-/// Get the best implementation of an EcbEncryptor
+/// Get the best implementation of an `EcbEncryptor`
 #[cfg(all(not(target_arch = "x86"), not(target_arch = "x86_64")))]
 pub fn ecb_encryptor<X: PaddingProcessor + Send + 'static>(
         key_size: KeySize,
@@ -74,7 +74,7 @@ pub fn ecb_encryptor<X: PaddingProcessor + Send + 'static>(
 }
 
 // aes in electronic codebook mode (ecb) decryption
-/// Get the best implementation of an EcbDecryptor
+/// Get the best implementation of an `EcbDecryptor`
 #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
 pub fn ecb_decryptor<X: PaddingProcessor + Send + 'static>(
         key_size: KeySize,
@@ -101,7 +101,7 @@ pub fn ecb_decryptor<X: PaddingProcessor + Send + 'static>(
     }
 }
 
-/// Get the best implementation of an EcbDecryptor
+/// Get the best implementation of an `EcbDecryptor`
 #[cfg(all(not(target_arch = "x86"), not(target_arch = "x86_64")))]
 pub fn ecb_decryptor<X: PaddingProcessor + Send + 'static>(
         key_size: KeySize,
@@ -124,7 +124,7 @@ pub fn ecb_decryptor<X: PaddingProcessor + Send + 'static>(
 }
 
 // aes in cipher block chaining mode (cbc) encryption
-/// Get the best implementation of a CbcEncryptor
+/// Get the best implementation of a `CbcEncryptor`
 #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
 pub fn cbc_encryptor<X: PaddingProcessor + Send + 'static>(
         key_size: KeySize,
@@ -152,7 +152,7 @@ pub fn cbc_encryptor<X: PaddingProcessor + Send + 'static>(
     }
 }
 
-/// Get the best implementation of a CbcEncryptor
+/// Get the best implementation of a `CbcEncryptor`
 #[cfg(all(not(target_arch = "x86"), not(target_arch = "x86_64")))]
 pub fn cbc_encryptor<X: PaddingProcessor + Send + 'static>(
         key_size: KeySize,
@@ -176,7 +176,7 @@ pub fn cbc_encryptor<X: PaddingProcessor + Send + 'static>(
 }
 
 // aes in cipher block chaining mode (cbc) decryption
-/// Get the best implementation of a CbcDecryptor
+/// Get the best implementation of a `CbcDecryptor`
 #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
 pub fn cbc_decryptor<X: PaddingProcessor + Send + 'static>(
         key_size: KeySize,
@@ -204,7 +204,7 @@ pub fn cbc_decryptor<X: PaddingProcessor + Send + 'static>(
     }
 }
 
-/// Get the best implementation of a CbcDecryptor
+/// Get the best implementation of a `CbcDecryptor`
 #[cfg(all(not(target_arch = "x86"), not(target_arch = "x86_64")))]
 pub fn cbc_decryptor<X: PaddingProcessor + Send + 'static>(
         key_size: KeySize,

src/aessafe.rs

@@ -89,38 +89,37 @@ data that is combined into the AES state by the AddRoundKey step as part of each
 decryption round. Processing the round key can be expensive, so this is done before encryption or
 decryption. Before encrypting or decrypting data, the data to be processed by be Bit Sliced into 8
 seperate variables where each variable holds equivalent bytes from the state. This Bit Sliced state
-is stored as a Bs8State<T>, where T is the type that stores each set of bits. The first
+is stored as a `Bs8State<T>`, where `T` is the type that stores each set of bits. The first
 implementation stores these bits in a u32 which permits up to 8 * 32 = 1024 bits of data to be
 processed at once. This implementation only processes a single block at a time, so, in reality, only
 512 bits are processed at once and the remaining 512 bits of the variables are unused. The 2nd
 implementation uses u32x4s - vectors of 4 u32s. Thus, we can process 8 * 128 = 4096 bits at once,
 which corresponds exactly to 8 blocks.
 
-The Bs8State struct implements the AesOps trait, which contains methods for each of the 4 main steps
-of the AES algorithm. The types, T, each implement the AesBitValueOps trait, which containts methods
-necessary for processing a collection or bit values and the AesOps trait relies heavily on this
+The `Bs8State` struct implements the `AesOps` trait, which contains methods for each of the 4 main steps
+of the AES algorithm. The types, `T`, each implement the `AesBitValueOps` trait, which containts methods
+necessary for processing a collection or bit values and the `AesOps` trait relies heavily on this
 trait to perform its operations.
 
-The Bs4State and Bs2State struct implement operations of various subfields of the full GF(2^8)
+The `Bs4State` and `Bs2State` struct implement operations of various subfields of the full GF(2^8)
 finite field which allows for efficient computation of the AES S-Boxes. See [7] for details.
 
 ## References
 
 [1] - "Cache-Collision Timing Attacks Against AES". Joseph Bonneau and Ilya Mironov.
-      http://www.jbonneau.com/doc/BM06-CHES-aes_cache_timing.pdf
+      <http://www.jbonneau.com/doc/BM06-CHES-aes_cache_timing.pdf>
 [2] - "Software mitigations to hedge AES against cache-based software side channel vulnerabilities".
-      Ernie Brickell, et al. http://eprint.iacr.org/2006/052.pdf.
+      Ernie Brickell, et al. <http://eprint.iacr.org/2006/052.pdf>.
 [3] - "Cache Attacks and Countermeasures: the Case of AES (Extended Version)".
-      Dag Arne Osvik, et al. tau.ac.il/~tromer/papers/cache.pdf‎.
+      Dag Arne Osvik, et al. <tau.ac.il/~tromer/papers/cache.pdf>‎.
 [4] - "A Fast New DES Implementation in Software". Eli Biham.
-      http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.52.5429&rep=rep1&type=pdf.
+      <http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.52.5429&rep=rep1&type=pdf>.
 [5] - "Faster and Timing-Attack Resistant AES-GCM". Emilia K ̈asper and Peter Schwabe.
-      http://www.chesworkshop.org/ches2009/presentations/01_Session_1/CHES2009_ekasper.pdf.
-[6] - "FAST AES DECRYPTION". Vinit Azad. http://webcache.googleusercontent.com/
-      search?q=cache:ld_f8pSgURcJ:csusdspace.calstate.edu/bitstream/handle/10211.9/1224/
-      Vinit_Azad_MS_Report.doc%3Fsequence%3D2+&cd=4&hl=en&ct=clnk&gl=us&client=ubuntu.
+      <http://www.chesworkshop.org/ches2009/presentations/01_Session_1/CHES2009_ekasper.pdf>.
+[6] - "FAST AES DECRYPTION". Vinit Azad.
+      <http://webcache.googleusercontent.com/search?q=cache:ld_f8pSgURcJ:csusdspace.calstate.edu/bitstream/handle/10211.9/1224/Vinit_Azad_MS_Report.doc%3Fsequence%3D2+&cd=4&hl=en&ct=clnk&gl=us&client=ubuntu>.
 [7] - "A Very Compact Rijndael S-box". D. Canright.
-      http://www.dtic.mil/cgi-bin/GetTRDoc?AD=ADA434781.
+      <http://www.dtic.mil/cgi-bin/GetTRDoc?AD=ADA434781>.
 */
 
 use std::ops::{BitAnd, BitXor, Not};

src/blockmodes.rs

@@ -19,29 +19,29 @@ use symmetriccipher::{BlockEncryptor, BlockEncryptorX8, Encryptor, BlockDecrypto
     SynchronousStreamCipher, SymmetricCipherError};
 use symmetriccipher::SymmetricCipherError::{InvalidPadding, InvalidLength};
 
-/// The BlockProcessor trait is used to implement modes that require processing complete blocks of
-/// data. The methods of this trait are called by the BlockEngine which is in charge of properly
+/// The `BlockProcessor` trait is used to implement modes that require processing complete blocks of
+/// data. The methods of this trait are called by the `BlockEngine` which is in charge of properly
 /// buffering input data.
 trait BlockProcessor {
     /// Process a block of data. The in_hist and out_hist parameters represent the input and output
     /// when the last block was processed. These values are necessary for certain modes.
     fn process_block(&mut self, in_hist: &[u8], out_hist: &[u8], input: &[u8], output: &mut [u8]);
 }
 
-/// A PaddingProcessor handles adding or removing padding
+/// A `PaddingProcessor` handles adding or removing padding
 pub trait PaddingProcessor {
     /// Add padding to the last block of input data
     /// If the mode can't handle a non-full block, it signals that error by simply leaving the block
-    /// as it is which will be detected as an InvalidLength error.
+    /// as it is which will be detected as an `InvalidLength` error.
     fn pad_input<W: WriteBuffer>(&mut self, input_buffer: &mut W);
 
     /// Remove padding from the last block of output data
     /// If false is returned, the processing fails
     fn strip_output<R: ReadBuffer>(&mut self, output_buffer: &mut R) -> bool;
 }
 
-/// The BlockEngine is implemented as a state machine with the following states. See comments in the
-/// BlockEngine code for more information on the states.
+/// The `BlockEngine` is implemented as a state machine with the following states. See comments in the
+/// `BlockEngine` code for more information on the states.
 #[derive(Clone, Copy)]
 enum BlockEngineState {
     FastMode,
@@ -53,28 +53,28 @@ enum BlockEngineState {
     Error(SymmetricCipherError)
 }
 
-/// BlockEngine buffers input and output data and handles sending complete block of data to the
-/// Processor object. Additionally, BlockEngine handles logic necessary to add or remove padding by
+/// `BlockEngine` buffers input and output data and handles sending complete block of data to the
+/// Processor object. Additionally, `BlockEngine` handles logic necessary to add or remove padding by
 /// calling the appropriate methods on the Processor object.
 struct BlockEngine<P, X> {
     /// The block sized expected by the Processor
     block_size: usize,
 
-    /// in_hist and out_hist keep track of data that was input to and output from the last
-    /// invocation of the process_block() method of the Processor. Depending on the mode, these may
+    /// `in_hist` and `out_hist` keep track of data that was input to and output from the last
+    /// invocation of the `process_block()` method of the Processor. Depending on the mode, these may
     /// be empty vectors if history is not needed.
     in_hist: Vec<u8>,
     out_hist: Vec<u8>,
 
     /// If some input data is supplied, but not a complete blocks worth, it is stored in this buffer
-    /// until enough arrives that it can be passed to the process_block() method of the Processor.
+    /// until enough arrives that it can be passed to the `process_block()` method of the Processor.
     in_scratch: OwnedWriteBuffer,
 
     /// If input data is processed but there isn't enough space in the output buffer to store it,
-    /// it is written into out_write_scratch. OwnedWriteBuffer's may be converted into
-    /// OwnedReaderBuffers without re-allocating, so, after being written, out_write_scratch is
-    /// turned into out_read_scratch. After that, if is written to the output as more output becomes
-    /// available. The main point is - only out_write_scratch or out_read_scratch contains a value
+    /// it is written into `out_write_scratch`. `OwnedWriteBuffer`s may be converted into
+    /// `OwnedReaderBuffer`s without re-allocating, so, after being written, `out_write_scratch` is
+    /// turned into `out_read_scratch`. After that, if is written to the output as more output becomes
+    /// available. The main point is - only `out_write_scratch` or `out_read_scratch` contains a value
     /// at any given time; never both.
     out_write_scratch: Option<OwnedWriteBuffer>,
     out_read_scratch: Option<OwnedReadBuffer>,
@@ -105,7 +105,7 @@ fn update_history(in_hist: &mut [u8], out_hist: &mut [u8], last_in: &[u8], last_
 }
 
 impl <P: BlockProcessor, X: PaddingProcessor> BlockEngine<P, X> {
-    /// Create a new BlockProcessor instance with the given processor and block_size. No history
+    /// Create a new `BlockProcessor` instance with the given processor and `block_size`. No history
     /// will be saved.
     fn new(processor: P, padding: X, block_size: usize) -> BlockEngine<P, X> {
         BlockEngine {
@@ -121,7 +121,7 @@ impl <P: BlockProcessor, X: PaddingProcessor> BlockEngine<P, X> {
         }
     }
 
-    /// Create a new BlockProcessor instance with the given processor, block_size, and initial input
+    /// Create a new `BlockProcessor` instance with the given processor, `block_size`, and initial input
     /// and output history.
     fn new_with_history(
             processor: P,
@@ -136,9 +136,9 @@ impl <P: BlockProcessor, X: PaddingProcessor> BlockEngine<P, X> {
         }
     }
 
-    /// This implements the FastMode state. Ideally, the encryption or decryption operation should
-    /// do the bulk of its work in FastMode. Significantly, FastMode avoids doing copies as much as
-    /// possible. The FastMode state does not handle the final block of data.
+    /// This implements the `FastMode` state. Ideally, the encryption or decryption operation should
+    /// do the bulk of its work in `FastMode`. Significantly, `FastMode` avoids doing copies as much as
+    /// possible. The `FastMode` state does not handle the final block of data.
     fn fast_mode<R: ReadBuffer, W: WriteBuffer>(
             &mut self,
             input: &mut R,
@@ -211,7 +211,7 @@ impl <P: BlockProcessor, X: PaddingProcessor> BlockEngine<P, X> {
         }
     }
 
-    /// This method implements the BlockEngine state machine.
+    /// This method implements the `BlockEngine` state machine.
     fn process<R: ReadBuffer, W: WriteBuffer>(
             &mut self,
             input: &mut R,
@@ -460,7 +460,7 @@ impl PaddingProcessor for PkcsPadding {
     }
 }
 
-/// Wraps a PaddingProcessor so that only pad_input() will actually be called.
+/// Wraps a `PaddingProcessor` so that only `pad_input()` will actually be called.
 pub struct EncPadding<X> {
     padding: X
 }
@@ -474,7 +474,7 @@ impl <X: PaddingProcessor> PaddingProcessor for EncPadding<X> {
     fn strip_output<R: ReadBuffer>(&mut self, _: &mut R) -> bool { true }
 }
 
-/// Wraps a PaddingProcessor so that only strip_output() will actually be called.
+/// Wraps a `PaddingProcessor` so that only `strip_output()` will actually be called.
 pub struct DecPadding<X> {
     padding: X
 }

src/cryptoutil.rs

@@ -244,7 +244,7 @@ impl <T> WriteExt for T where T: io::Write {
     }
 }
 
-/// symm_enc_or_dec() implements the necessary functionality to turn a SynchronousStreamCipher into
+/// `symm_enc_or_dec()` implements the necessary functionality to turn a `SynchronousStreamCipher` into
 /// an Encryptor or Decryptor
 pub fn symm_enc_or_dec<S: SynchronousStreamCipher, R: ReadBuffer, W: WriteBuffer>(
         c: &mut S,
@@ -266,7 +266,7 @@ fn to_bits(x: u64) -> (u64, u64) {
     (x >> 61, x << 3)
 }
 
-/// Adds the specified number of bytes to the bit count. panic!() if this would cause numeric
+/// Adds the specified number of bytes to the bit count. `panic!()` if this would cause numeric
 /// overflow.
 pub fn add_bytes_to_bits(bits: u64, bytes: u64) -> u64 {
     let (new_high_bits, new_low_bits) = to_bits(bytes);
@@ -279,7 +279,7 @@ pub fn add_bytes_to_bits(bits: u64, bytes: u64) -> u64 {
 }
 
 /// Adds the specified number of bytes to the bit count, which is a tuple where the first element is
-/// the high order value. panic!() if this would cause numeric overflow.
+/// the high order value. `panic!()` if this would cause numeric overflow.
 pub fn add_bytes_to_bits_tuple
         (bits: (u64, u64), bytes: u64) -> (u64, u64) {
     let (new_high_bits, new_low_bits) = to_bits(bytes);
@@ -322,8 +322,8 @@ pub fn add_bytes_to_bits_tuple
 }
 
 
-/// A FixedBuffer, likes its name implies, is a fixed size buffer. When the buffer becomes full, it
-/// must be processed. The input() method takes care of processing and then clearing the buffer
+/// A `FixedBuffer`, likes its name implies, is a fixed size buffer. When the buffer becomes full, it
+/// must be processed. The `input()` method takes care of processing and then clearing the buffer
 /// automatically. However, other methods do not and require the caller to process the buffer. Any
 /// method that modifies the buffer directory or provides the caller with bytes that can be modifies
 /// results in those bytes being marked as used by the buffer.
@@ -482,7 +482,7 @@ impl FixedBuffer128 {
 impl_fixed_buffer!(FixedBuffer128, 128);
 
 
-/// The StandardPadding trait adds a method useful for various hash algorithms to a FixedBuffer
+/// The `StandardPadding` trait adds a method useful for various hash algorithms to a `FixedBuffer`
 /// struct.
 pub trait StandardPadding {
     /// Add standard padding to the buffer. The buffer must not be full when this method is called

src/fortuna.rs

@@ -35,7 +35,7 @@
  * as its parent.
  *
  * However, this appears not to be possible in Rust, due to
- *     https://github.com/rust-lang/rust/issues/16799
+ *     <https://github.com/rust-lang/rust/issues/16799>
  * The reason is that Rust's process management all happens through its
  * stdlib runtime, which explicitly does not support forking, so it provides
  * no mechanism with which to detect forks.
@@ -398,7 +398,7 @@ mod tests {
         let mut output = [0; 100];
         // Expected output from experiments with pycryto
         // Note that this does not match the results for the Go implementation
-        // as described at http://www.seehuhn.de/pages/fortuna ... I believe
+        // as described at <http://www.seehuhn.de/pages/fortuna> ... I believe
         // this is because the author there is reusing some Fortuna state from
         // the previous test. These results agree with pycrypto on a fresh slate
         let mut f = Fortuna::new_unseeded();

src/hkdf.rs

@@ -5,7 +5,7 @@
 // except according to those terms.
 
 //! This module implements the HMAC-based Extract-and-Expand Key
-//! Derivation Function as specified by  https://tools.ietf.org/html/rfc5869.
+//! Derivation Function as specified by <https://tools.ietf.org/html/rfc5869>.
 
 use std::iter::repeat;
 use cryptoutil::copy_memory;
@@ -21,7 +21,7 @@ use mac::Mac;
 /// * digest - The digest function to use.
 /// * salt - The optional salt value (a non-secret random value) to use.
 /// * ikm - The input keying material to use.
-/// * prk - The output buffer to fill with a digest.output_bytes() length
+/// * prk - The output buffer to fill with a `digest.output_bytes()` length
 ///         pseudo random key.
 pub fn hkdf_extract<D: Digest>(mut digest: D, salt: &[u8], ikm: &[u8], prk: &mut [u8]) {
     assert!(prk.len() == digest.output_bytes());
@@ -38,7 +38,7 @@ pub fn hkdf_extract<D: Digest>(mut digest: D, salt: &[u8], ikm: &[u8], prk: &mut
 ///
 /// # Arguments
 /// * digest - The digest function to use.
-/// * prk - The pseudorandom key of at least digest.output_bytes() octets.
+/// * prk - The pseudorandom key of at least `digest.output_bytes()` octets.
 /// * info - The optional context and application specific information to use.
 /// * okm - The output buffer to fill with the derived key value.
 pub fn hkdf_expand<D: Digest>(mut digest: D, prk: &[u8], info: &[u8], okm: &mut [u8]) {

src/mac.rs

@@ -5,13 +5,13 @@
 // except according to those terms.
 
 /*!
- * The mac module defines the Message Authentication Code (Mac) trait.
+ * The mac module defines the Message Authentication Code (`Mac`) trait.
  */
 
 use util::fixed_time_eq;
 
 /**
- * The Mac trait defines methods for a Message Authentication function.
+ * The `Mac` trait defines methods for a Message Authentication function.
  */
 pub trait Mac {
     /**
@@ -29,7 +29,7 @@ pub trait Mac {
     fn reset(&mut self);
 
     /**
-     * Obtain the result of a Mac computation as a MacResult.
+     * Obtain the result of a Mac computation as a `MacResult`.
      */
     fn result(&mut self) -> MacResult;
 
@@ -47,15 +47,15 @@ pub trait Mac {
 }
 
 /**
- * A MacResult wraps a Mac code and provides a safe Eq implementation that runs in fixed time.
+ * A `MacResult` wraps a Mac code and provides a safe Eq implementation that runs in fixed time.
  */
 pub struct MacResult {
     code: Vec<u8>
 }
 
 impl MacResult {
     /**
-     * Create a new MacResult.
+     * Create a new `MacResult`.
      */
     pub fn new(code: &[u8]) -> MacResult {
         MacResult {
@@ -64,7 +64,7 @@ impl MacResult {
     }
 
     /**
-     * Create a new MacResult taking ownership of the specified code value.
+     * Create a new `MacResult` taking ownership of the specified code value.
      */
     pub fn new_from_owned(code: Vec<u8>) -> MacResult {
         MacResult {