Added documentation for the src/enc module

src/enc/encoder.rs

@@ -1,3 +1,5 @@
+//! Contains
+
 use super::{write::Writer, Encode};
 use crate::{
     config::{Config, Endian, IntEncoding},
@@ -5,19 +7,40 @@ use crate::{
 };
 use core::marker::PhantomData;
 
+/// An Encoder that writes bytes into a given writer `W`.
+///
+/// This struct should rarely be used.
+/// In most cases, prefer any of the `encode` functions.
+///
+/// The ByteOrder that is chosen will impact the endianness that
+/// is used to write integers to the writer.
+///
+/// ```
+/// # use bincode::enc::{write::SliceWriter, Encoder, Encodeable};
+/// # use bincode::config::{self, Config};
+/// # let config = config::Default.with_fixed_int_encoding().with_big_endian();
+/// let slice: &mut [u8] = &mut [0, 0, 0, 0];
+/// let mut encoder = Encoder::new(SliceWriter::new(slice), config);
+/// // this u32 can be any Encodable
+/// 5u32.encode(&mut encoder).unwrap();
+/// assert_eq!(encoder.into_writer().bytes_written(), 4);
+/// assert_eq!(slice, [0, 0, 0, 5]);
+/// ```
 pub struct Encoder<W: Writer, C: Config> {
     writer: W,
     config: PhantomData<C>,
 }
 
 impl<W: Writer, C: Config> Encoder<W, C> {
-    pub fn new(writer: W) -> Encoder<W, C> {
+    /// Create a new Encoder
+    pub fn new(writer: W, _config: C) -> Encoder<W, C> {
         Encoder {
             writer,
             config: PhantomData,
         }
     }
 
+    /// Return the underlying writer
     pub fn into_writer(self) -> W {
         self.writer
     }

src/enc/mod.rs

@@ -1,3 +1,5 @@
+//! Encoder-based structs and traits.
+
 mod encoder;
 mod impls;
 
@@ -7,27 +9,48 @@ pub mod write;
 
 pub use self::encoder::Encoder;
 
+/// Any source that can encode types. This type is most notably implemented for [Encoder].
+///
+/// [Encoder]: ../struct.Encoder.html
 pub trait Encodeable {
+    /// Encode a given type.
     fn encode<E: Encode>(&self, encoder: E) -> Result<(), EncodeError>;
 }
 
+/// Helper trait to encode basic types into.
 pub trait Encode {
+    /// Encode an `u8`
     fn encode_u8(&mut self, val: u8) -> Result<(), EncodeError>;
+    /// Encode an `u16`
     fn encode_u16(&mut self, val: u16) -> Result<(), EncodeError>;
+    /// Encode an `u32`
     fn encode_u32(&mut self, val: u32) -> Result<(), EncodeError>;
+    /// Encode an `u64`
     fn encode_u64(&mut self, val: u64) -> Result<(), EncodeError>;
+    /// Encode an `u128`
     fn encode_u128(&mut self, val: u128) -> Result<(), EncodeError>;
+    /// Encode an `usize`
     fn encode_usize(&mut self, val: usize) -> Result<(), EncodeError>;
 
+    /// Encode an `i8`
     fn encode_i8(&mut self, val: i8) -> Result<(), EncodeError>;
+    /// Encode an `i16`
     fn encode_i16(&mut self, val: i16) -> Result<(), EncodeError>;
+    /// Encode an `i32`
     fn encode_i32(&mut self, val: i32) -> Result<(), EncodeError>;
+    /// Encode an `i64`
     fn encode_i64(&mut self, val: i64) -> Result<(), EncodeError>;
+    /// Encode an `i128`
     fn encode_i128(&mut self, val: i128) -> Result<(), EncodeError>;
+    /// Encode an `isize`
     fn encode_isize(&mut self, val: isize) -> Result<(), EncodeError>;
 
+    /// Encode an `f32`
     fn encode_f32(&mut self, val: f32) -> Result<(), EncodeError>;
+    /// Encode an `f64`
     fn encode_f64(&mut self, val: f64) -> Result<(), EncodeError>;
+    /// Encode a slice. Exactly `val.len()` bytes must be encoded, else an error should be thrown.
     fn encode_slice(&mut self, val: &[u8]) -> Result<(), EncodeError>;
+    /// Encode an array. Exactly `N` bytes must be encoded, else an error should be thrown.
     fn encode_array<const N: usize>(&mut self, val: [u8; N]) -> Result<(), EncodeError>;
 }

src/enc/write.rs

@@ -1,23 +1,45 @@
+//! This module contains writer-based structs and traits.
+//!
+//! Because `std::io::Write` is only limited to `std` and not `core`, we provide our own [Writer].
+
 use crate::error::EncodeError;
 
+/// Trait that indicates that a struct can be used as a destination to encode data too. This is used by [Encodeable]
+///
+/// [Encodeable]: ../trait.Encodeable.html
 pub trait Writer {
+    /// Write `bytes` to the underlying writer. Exactly `bytes.len()` bytes must be written, or else an error should be returned.
     fn write(&mut self, bytes: &[u8]) -> Result<(), EncodeError>;
 }
 
+/// A helper struct that implements `Writer` for a `&[u8]` slice.
+///
+/// ```
+/// use bincode::enc::write::{Writer, SliceWriter};
+///
+/// let destination = &mut [0u8; 100];
+/// let mut writer = SliceWriter::new(destination);
+/// writer.write(&[1, 2, 3, 4, 5]).unwrap();
+///
+/// assert_eq!(writer.bytes_written(), 5);
+/// assert_eq!(destination[0..6], [1, 2, 3, 4, 5, 0]);
+/// ```
 pub struct SliceWriter<'storage> {
     slice: &'storage mut [u8],
     idx: usize,
 }
 
 impl<'storage> SliceWriter<'storage> {
-    pub(crate) fn new(bytes: &'storage mut [u8]) -> SliceWriter<'storage> {
+    /// Create a new instance of `SliceWriter` with the given byte array.
+    pub fn new(bytes: &'storage mut [u8]) -> SliceWriter<'storage> {
         SliceWriter {
             slice: bytes,
             idx: 0,
         }
     }
 
-    pub(crate) fn bytes_written(&self) -> usize {
+    /// Return the amount of bytes written so far.
+    pub fn bytes_written(&self) -> usize {
         self.idx
     }
 }