fix glaslos#12 - add documentation

example_test.go

@@ -0,0 +1,46 @@
+package ssdeep_test
+
+import (
+	"github.com/glaslos/ssdeep"
+	"math/rand"
+	"fmt"
+	"os"
+	"log"
+)
+
+func ExampleNew() {
+	h := ssdeep.New()
+
+	// Create data larger than 4096 bytes
+	data := make([]byte, 4097)
+	rand.Read(data)
+
+	h.Write(data)
+	fmt.Printf("%s", h.Sum(nil))
+}
+
+func ExampleFuzzyFilename() {
+	f, err := os.Open("file.txt")
+	if err != nil {
+		log.Fatal(err)
+	}
+	defer f.Close()
+
+	h, err := ssdeep.FuzzyFile(f)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	fmt.Println(h)
+}
+
+func ExampleFuzzyBytes() {
+	buffer := make([]byte, 4097)
+	rand.Read(buffer)
+	h, err := ssdeep.FuzzyBytes(buffer)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	fmt.Println(h)
+}

score.go

@@ -7,6 +7,10 @@ import (
 	"errors"
 )
 
+// Computes the match score between two fuzzy hash signatures.
+// Returns a value from zero to 100 indicating the match score of the two signatures.
+// A match score of zero indicates the signatures did not match.
+// Returns an error when one of the inputs are not valid signatures.
 func Distance(hash1, hash2 string) (score int, err error) {
 	hash1BlockSize, hash1String1, hash1String2, err := splitSsdeep(hash1)
 	if err != nil {

ssdeep.go

@@ -162,6 +162,10 @@ func (state *ssdeepState) fuzzyReader(f fuzzyReader, n int) (string, error) {
 	return fmt.Sprintf("%d:%s:%s", state.blockSize, state.hashString1, state.hashString2), nil
 }
 
+// FuzzyFilename computes the fuzzy hash of a file.
+// FuzzyFilename will opens, reads, and hashes the contents of the file 'filename'.
+// It is the caller's responsibility to append the filename to the result after computation.
+// Returns an error when the file doesn't exist or ssdeep could not be computed on the file.
 func FuzzyFilename(filename string) (string, error) {
 	f, err := os.Open(filename)
 	if err != nil {
@@ -172,6 +176,12 @@ func FuzzyFilename(filename string) (string, error) {
 	return FuzzyFile(f)
 }
 
+// FuzzyFile computes the fuzzy hash of a file using os.File pointer.
+// FuzzyFile will computes the fuzzy hash of the contents of the open file, starting at the beginning of the file.
+// When finished, the file pointer is returned to its original position.
+// If an error occurs, the file pointer's value is undefined.
+// It is the callers's responsibility to append the filename to the result after computation.
+// Returns an error when ssdeep could not be computed on the file.
 func FuzzyFile(f *os.File) (string, error) {
 	currentPosition, err := f.Seek(0, io.SeekCurrent)
 	if err != nil {
@@ -194,6 +204,9 @@ func FuzzyFile(f *os.File) (string, error) {
 	return result, nil
 }
 
+// FuzzyBytes computes the fuzzy hash of a slice of byte.
+// It is the caller's responsibility to append the filename, if any, to result after computation.
+// Returns an error when ssdeep could not be computed on the buffer.
 func FuzzyBytes(buffer []byte) (string, error) {
 	state := newSsdeepState()
 	n := len(buffer)
@@ -239,6 +252,8 @@ func (d *digest) BlockSize() int {
 	return minFileSize
 }
 
+// New returns a new hash.Hash computing the ssdeep checksum.
+// If Sum fails to produce ssdeep checksum, it will return nil instead of byte slice
 func New() hash.Hash {
 	digest := new(digest)
 	digest.Reset()