From 28a08a1401467fb4cf86a4430e02ff7f682d8212 Mon Sep 17 00:00:00 2001
From: daniel <bauer@cbs.tu-darmstadt.de>
Date: Thu, 16 Apr 2020 14:37:59 +0200
Subject: [PATCH] documentation

---
 src/frame.rs   | 12 ++++++----
 src/lib.rs     | 62 ++++++++++++++++++++++++++++++++++++++++++++++----
 src/xdrfile.rs |  0
 3 files changed, 66 insertions(+), 8 deletions(-)
 delete mode 100644 src/xdrfile.rs

diff --git a/src/frame.rs b/src/frame.rs
index 82dcf21..f62d1dc 100644
--- a/src/frame.rs
+++ b/src/frame.rs
@@ -1,6 +1,6 @@
 use std::fmt;
 
-/// Representation of a single frame of an MD trajectory
+/// A frame represents a single step in a trajectory.
 #[derive(Clone)]
 pub struct Frame {
     /// Number of atoms in the frame
@@ -9,7 +9,7 @@ pub struct Frame {
     /// Trajectory step
     pub step: u32,
 
-    /// Time step
+    /// Time step (usually in picoseconds)
     pub time: f32,
 
     /// 3x3 box vector 
@@ -21,13 +21,13 @@ pub struct Frame {
 
 impl Default for Frame {
     fn default() -> Frame {
-        return Frame { 
+        Frame { 
             num_atoms: 0,
             step: 0,
             time: 0.0,
             box_vector: [[0.0; 3]; 3],
             coords: Vec::with_capacity(0)
-        };
+        }
     }
 }
 
@@ -40,10 +40,12 @@ impl fmt::Debug for Frame {
 }
 
 impl Frame {
+    /// Creates an empty frame with a capacity of 0
     pub fn new() -> Frame {
         Frame{ ..Default::default() }
     }
 
+    /// Creates a frame with the given capacity
     pub fn with_capacity(num_atoms: u32) -> Frame {
         Frame {
             num_atoms: num_atoms,
@@ -53,6 +55,7 @@ impl Frame {
 
     }
 
+    /// Filters the frame by removing all atoms not matching the given indeces. 
     pub fn filter_coords(self: &mut Frame, indeces: &[usize]) {
         self.coords = self.coords.iter() 
             .map(|elem| elem.clone())
@@ -63,6 +66,7 @@ impl Frame {
         self.num_atoms = self.coords.len() as u32;
     }   
 
+    /// Length of the frame (number of atoms)
     pub fn len(self: &Frame) -> usize {
         self.num_atoms as usize
     } 
diff --git a/src/lib.rs b/src/lib.rs
index 3b5f62d..c8ca9bd 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,5 +1,46 @@
+//! # xdrfile
+//! Read and write xdr trajectory files in .xtc and .trr file format
+//!
+//! This crate is mainly intended to be a wrapper around the GROMACS libxdrfile
+//! XTC library and provides basic functionality to read and write xtc and trr
+//! files with a safe api.
+//!
+//! # Basic usage example
+//! ```rust
+//! use xdrfile::*;
+//! use std::path::Path; 
+//!
+//! let mut path = Path::new("tests/1l2y.xtc");
+//! // get a handle to the file
+//! let mut trj = XTCTrajectory::open(path, FileMode::Read).unwrap();
+//!
+//! // find number of atoms in the file
+//! let num_atoms = trj.get_num_atoms().unwrap();
+//! 
+//! // a frame object is used to get to read or write from a trajectory
+//! // without instantiating data arrays for every step
+//! let mut frame = Frame::with_capacity(num_atoms);
+//! 
+//! // read the first trame of the trajectory
+//! let result = trj.read(&mut frame);
+//! match result {
+//!    Ok(_) => {
+//!        assert_eq!(frame.step, 1);
+//!        assert_eq!(frame.num_atoms, num_atoms);
+//! 
+//!        let first_atom_coords = frame.coords[0];
+//!        assert_eq!(first_atom_coords, [-0.8901, 0.4127, -0.055499997]);
+//!    }
+//!    Err(msg) => {
+//!        panic!("Something went wrong: {}", msg);    
+//!    }
+//! }
+//! ``` 
+
+
 #[cfg(test)]
 #[macro_use] extern crate assert_approx_eq;
+extern crate lazy_init;
 
 mod frame;
 pub mod c_abi; 
@@ -25,7 +66,7 @@ pub enum FileMode {
 
 impl FileMode {
     pub fn value(&self) -> &str {
-        return match *self {
+        match *self {
             FileMode::Write => "w",
             FileMode::Append => "a",
             FileMode::Read => "r",
@@ -37,6 +78,7 @@ fn path_to_cstring(path: &Path) -> CString {
         CString::new(path.to_str().unwrap()).unwrap()
     }
 
+/// A safe wrapper around the c implementation of an XDRFile
 struct XDRFile {
     xdrfile: *mut XDRFILE,
     filemode: FileMode,
@@ -54,16 +96,16 @@ impl XDRFile {
         
             if ! xdrfile.is_null() {
                 let path = String::from(path.to_str().unwrap());
-                return Ok(XDRFile { xdrfile, filemode, path });
+                Ok(XDRFile { xdrfile, filemode, path })
             } else {  // Something went wrong. But the C api does not tell us what
-                return Err(err_msg("Failed to open trajectory file"));
+                Err(err_msg("Failed to open trajectory file"))
             }
         }
     }
 }
 
 impl Drop for XDRFile {
-    // Close the underlying xdr file on drop
+    /// Close the underlying xdr file on drop
     fn drop(&mut self) {
         unsafe {
             xdrfile::xdrfile_close(self.xdrfile);
@@ -71,13 +113,23 @@ impl Drop for XDRFile {
     } 
 }
 
+/// The trajectory trait defines shared methods for xtc and trr trajectories
 pub trait Trajectory {
+
+    /// Read the next step of the trajectory into the frame object
     fn read(&mut self, frame: &mut Frame) -> Result<(), Error>;
+
+    /// Write the frame to the trajectory file
     fn write(&mut self, frame: &Frame) -> Result<(), Error>;
+    
+    /// Flush the trajectory file
     fn flush(&mut self) -> Result<(), Error>;
+
+    /// Get the number of atoms from the give trajectory
     fn get_num_atoms(&mut self) -> Result<u32, Error>; 
 }
 
+/// Read/Write XTC Trajectories
 pub struct XTCTrajectory {
     handle: XDRFile,
     precision: Cell<f32>,  // internal mutability required for read method
@@ -162,6 +214,8 @@ impl Trajectory for XTCTrajectory {
     }
 }
 
+
+/// Read/Write TRR Trajectories
 pub struct TRRTrajectory {
     handle: XDRFile,
     num_atoms: Lazy<Result<u32, Error>>
diff --git a/src/xdrfile.rs b/src/xdrfile.rs
deleted file mode 100644
index e69de29..0000000