From 96e42a84431bb9a65136a0ae9d439098b57aca95 Mon Sep 17 00:00:00 2001
From: "Frederick F. Kautz IV" <fkautz@alumni.cmu.edu>
Date: Sat, 29 Nov 2014 13:18:52 -0800
Subject: [PATCH] Adding initial documentation to erasure package

---
 pkgs/erasure/doc.go    | 49 ++++++++++++++++++++++++++++++++++++++++++
 pkgs/erasure/encode.go | 12 ++++++++++-
 2 files changed, 60 insertions(+), 1 deletion(-)
 create mode 100644 pkgs/erasure/doc.go

diff --git a/pkgs/erasure/doc.go b/pkgs/erasure/doc.go
new file mode 100644
index 000000000..33cb4a1dd
--- /dev/null
+++ b/pkgs/erasure/doc.go
@@ -0,0 +1,49 @@
+// Package erasure is a Go wrapper for the Intel Intelligent Storage
+// Acceleration Library (Intel ISA-L).  Intel ISA-L is a CPU optimized
+// implementation of erasure code.
+//
+// For more information on Intel ISA-L, please visit:
+// https://01.org/intel%C2%AE-storage-acceleration-library-open-source-version
+//
+// Usage
+//
+// TODO: Explain Encode and Decode inputs and outputs
+//
+// TODO: Explain matrix size and how it corresponds to protection level
+//
+// Encoding data may be performed in 3 steps.
+//
+//  1. Create a validated set of encoder parameters
+//  2. Create a new encoder
+//  3. Encode data
+//
+// Decoding data is also performed in 3 steps.
+//
+//  1. Create a validated set of encoder parameters
+//  2. Create a new encoder
+//  3. Decode data
+//
+// Encoder parameters contain four configurable elements:
+//  ValidateParams(k, m, w, technique int) (EncoderParams, error)
+//  k - Number of rows in matrix
+//  m - Number of colums in matrix
+//  w - Word size, typically 8 or aligned by 8.
+//  technique - Matrix type, can be either CAUCHY (recommended) or VANDERMONDE
+//  constraints: k + m < 256
+//
+// Example
+//
+//
+// Creating and using an encoder
+//  var bytes []byte
+//  params := erasure.ValidateParams(10,5, 8, erasure.CAUCHY)
+//  encoder := erasure.NewEncoder(params)
+//  encodedData, length := encoder.Encode(bytes)
+//
+// Creating and using a decoder
+//  var encodedData [][]byte
+//  var length int
+//  params := erasure.ValidateParams(10,5, 8, erasure.CAUCHY)
+//  encoder := erasure.NewEncoder(params)
+//  originalData, err := encoder.Decode(encodedData, length)
+package erasure
diff --git a/pkgs/erasure/encode.go b/pkgs/erasure/encode.go
index c299a53dd..32ce9dbf0 100644
--- a/pkgs/erasure/encode.go
+++ b/pkgs/erasure/encode.go
@@ -42,12 +42,14 @@ const (
 	M = 3
 )
 
+// EncoderParams is a configuration set for building an encoder. It is created using ValidateParams.
 type EncoderParams struct {
 	k,
 	m,
 	technique int // cauchy or vandermonde matrix (RS)
 }
 
+// Encoder is an object used to encode and decode data.
 type Encoder struct {
 	p *EncoderParams
 	k,
@@ -58,7 +60,11 @@ type Encoder struct {
 	decode_tbls *C.uchar
 }
 
-// Parameter validation
+// ParseEncoderParams creates an EncoderParams object.
+//
+// k and n represent the matrix size, which corresponds to the protection level.
+//
+// technique is the matrix type. Valid inputs are CAUCHY (recommended) or VANDERMONDE.
 func ParseEncoderParams(k, m, technique int) (*EncoderParams, error) {
 	if k < 1 {
 		return nil, errors.New("k cannot be zero")
@@ -88,6 +94,7 @@ func ParseEncoderParams(k, m, technique int) (*EncoderParams, error) {
 	}, nil
 }
 
+// NewEncoder creates an encoder with a given set of parameters.
 func NewEncoder(ep *EncoderParams) *Encoder {
 	var k = C.int(ep.k)
 	var m = C.int(ep.m)
@@ -110,6 +117,9 @@ func NewEncoder(ep *EncoderParams) *Encoder {
 	}
 }
 
+// Encode encodes a block of data. The input is the original data. The output
+// is a 2 tuple containing (k + m) chunks of erasure encoded data and the
+// length of the original object.
 func (e *Encoder) Encode(block []byte) ([][]byte, int) {
 	var block_len = len(block)