add docstrings for durandal::bin

src/durandal/bin.rs

@@ -4,15 +4,18 @@ use crate::durandal::err::*;
 use std::{fmt,
           num::NonZeroU16};
 
-pub type Ident = [u8; 4];
-
 pub trait BinUtil
 {
-   // Checked
+   /// Returns a four-character-code identifier from `self` at `i`.
    fn c_iden(&self, i: usize) -> ResultS<Ident>;
+
+   /// Returns a big-endian `u32` from `self` at `i`.
    fn c_u32b(&self, i: usize) -> ResultS<u32>;
+
+   /// Returns a big-endian `u16` from `self` at `i`.
    fn c_u16b(&self, i: usize) -> ResultS<u16>;
 
+   /// Returns a big-endian `i32` from `self` at `i`.
    fn c_i32b(&self, i: usize) -> ResultS<i32>
    {
       match self.c_u32b(i) {
@@ -20,6 +23,8 @@ pub trait BinUtil
          Err(e) => Err(e),
       }
    }
+
+   /// Returns a big-endian `i16` from `self` at `i`.
    fn c_i16b(&self, i: usize) -> ResultS<i16>
    {
       match self.c_u16b(i) {
@@ -28,49 +33,35 @@ pub trait BinUtil
       }
    }
 
-   // Optional
+   /// The same as `c_iden`, but returns `Option`.
    fn o_iden(&self, i: usize) -> Option<Ident>
    {
       self.c_iden(i).ok()
    }
+
+   /// The same as `c_u32b`, but returns `Option`.
    fn o_u32b(&self, i: usize) -> Option<u32>
    {
       self.c_u32b(i).ok()
    }
+
+   /// The same as `c_u16b`, but returns `Option`.
    fn o_u16b(&self, i: usize) -> Option<u16>
    {
       self.c_u16b(i).ok()
    }
+
+   /// The same as `c_i32b`, but returns `Option`.
    fn o_i32b(&self, i: usize) -> Option<i32>
    {
       self.c_i32b(i).ok()
    }
+
+   /// The same as `c_i16b`, but returns `Option`.
    fn o_i16b(&self, i: usize) -> Option<i16>
    {
       self.c_i16b(i).ok()
    }
-
-   // Unchecked
-   fn b_iden(&self, i: usize) -> Ident
-   {
-      self.c_iden(i).unwrap()
-   }
-   fn b_u32b(&self, i: usize) -> u32
-   {
-      self.c_u32b(i).unwrap()
-   }
-   fn b_u16b(&self, i: usize) -> u16
-   {
-      self.c_u16b(i).unwrap()
-   }
-   fn b_i32b(&self, i: usize) -> i32
-   {
-      self.c_i32b(i).unwrap()
-   }
-   fn b_i16b(&self, i: usize) -> i16
-   {
-      self.c_i16b(i).unwrap()
-   }
 }
 
 impl BinUtil for [u8]
@@ -106,23 +97,11 @@ impl BinUtil for [u8]
    }
 }
 
-pub fn d_u32b(n: u32) -> [u8; 4]
-{
-   n.to_be_bytes()
-}
-pub fn d_u16b(n: u16) -> [u8; 2]
-{
-   n.to_be_bytes()
-}
-pub fn d_i32b(n: i32) -> [u8; 4]
-{
-   d_u32b(n as u32)
-}
-pub fn d_i16b(n: i16) -> [u8; 2]
-{
-   d_u16b(n as u16)
-}
+/// A four-character-code identifier.
+pub type Ident = [u8; 4];
 
+/// An object identified by a `u16` which may be `u16::max_value()` to
+/// represent None.
 pub struct ObjID(Option<NonZeroU16>);
 
 impl fmt::Debug for ObjID
@@ -138,6 +117,7 @@ impl fmt::Debug for ObjID
 
 impl ObjID
 {
+   /// Creates an `ObjID` from a `u16`.
    pub fn from_repr(n: u16) -> ObjID
    {
       if n == u16::max_value() {
@@ -147,6 +127,7 @@ impl ObjID
       }
    }
 
+   /// Returns the `u16` representation of an `ObjID`.
    pub fn get_repr(&self) -> u16
    {
       match self.0 {
@@ -155,6 +136,7 @@ impl ObjID
       }
    }
 
+   /// Returns the `Option` representation of an `ObjID`.
    pub fn get(&self) -> Option<u16>
    {
       match self.0 {