feat: doc build deps and build process

README.md

@@ -0,0 +1,41 @@
+[![status-badge](https://ci.batsense.net/api/badges/109/status.svg)](https://ci.batsense.net/repos/109)
+
+---
+
+# gomcaptcha: Go library that implements mCaptcha PoW
+
+## Overview
+
+Normal usage within mCaptcha ecosystem will look like this:
+
+1. mCaptcha server presents challenge parameters (`difficulty_factor`, salt, and challenge phrase)
+2. Visitor computes Proof-of-Work using parameters received
+3. Visitor submits Proof-of-Work to mCaptcha server and receives
+   authorization token if Proof-of-Work is valid.
+4. Visitor submits Proof-of-Work to protected resource/server
+
+This library implements step #2 from this process.
+
+## Dependencies
+
+1. [Rust compiler](https://rustup.rs): This library is a thin wrapper
+   over [mcaptcha-pow-ffi](./mcaptcha-pow-ffi), which has to be compiled
+   first before this library can be used.
+2. Go
+3. GNU Make
+
+Compile Rust FFI library:
+
+```bash
+make rust.build
+```
+
+Run example:
+
+```bash
+make example
+```
+
+## Usage
+
+Please refer to [example](./examples/main.go).

gomcaptcha.go

@@ -1,3 +1,5 @@
+// Go library that implements mCaptcha PoW.
+// It is a wrapper over [mcaptcha_pow_sha256](https://crates.io/crates/mcaptcha_pow_sha256).
 package gomcaptcha
 
 /*
@@ -7,11 +9,15 @@ package gomcaptcha
 */
 import "C"
 
+// Struct representing Proof-of-Work
 type ProofOfWork struct {
 	Nonce  uint64
 	Result string
 }
 
+// Compute Proof-of-Work over the challenge parameters presented by mCaptcha.
+// All input data will be supplied by the mCaptcha instance.
+// Outputs Proof-of-Work.
 func ProveWork(salt string, phrase string, difficulty uint) ProofOfWork {
 	res := C.prove_work(C.CString(salt),
 		C.CString(phrase), C.uint(difficulty))
@@ -23,6 +29,8 @@ func ProveWork(salt string, phrase string, difficulty uint) ProofOfWork {
 
 }
 
+// / Check if Proof-of-Work is of sufficient difficulty. Use same salt and difficulty
+// values used to compute PoW.
 func (v ProofOfWork) IsSufficientDifficulty(salt string, difficulty uint) bool {
 	res := C.is_sufficient_difficulty(
 		C.ulong(v.Nonce),
@@ -33,6 +41,8 @@ func (v ProofOfWork) IsSufficientDifficulty(salt string, difficulty uint) bool {
 
 }
 
+// / Check if Proof-of-Work is valid. Use same challenge phrase and salt values
+// used to compute PoW.
 func (v ProofOfWork) IsValidProof(phrase string, salt string) bool {
 	res := C.is_valid_proof(
 		C.ulong(v.Nonce),