Add ldoc based documentation

5 files changed, 87 insertions, 0 deletions

diff --git a/.gitignore b/.gitignore
index 005ec35..d1437fe 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,5 @@
 *.so
 *.a
 *.o
+html/
+*~
diff --git a/Makefile b/Makefile
index 070b1b2..7ac8504 100644
--- a/Makefile
+++ b/Makefile
@@ -109,6 +109,7 @@ all: lua-5.1-try lua-5.2-try
 clean:
 	$(RM) scrypt-5.1.so scrypt-5.2.so scrypt.so
 	$(RM) luascrypt.o
+	$(RM) -r html
 
 %.o: %.c
 	 $(CC) $(CFLAGS) -fPIC $(LUA51_INC) -c $< -o $@
@@ -134,3 +135,5 @@ scrypt-5.2.so: luascrypt.o
 	 $(CC) $(CFLAGS) -shared -o $@ $^ $(LUA51_LIB) $(SCRYPT_LIBS)
 
 
+doc:
+	@ldoc .
diff --git a/README b/README
new file mode 100644
index 0000000..9bed714
--- /dev/null
+++ b/README
@@ -0,0 +1,22 @@
+lua-scrypt
+==========
+
+lua-scrypt is a binding to libscrypt which is a password crypting and
+verification library.  lua-scrypt uses the [libscrypt][] library and
+provides a simple interface for hashing and verifying passwords.
+
+    local scrypt = require "scrypt"
+    
+    local hash = scrypt.hash_password("Hello world")
+
+    assert(scrypt.verify_password(hash, "Hello world"))
+
+Thanks
+======
+
+Originally, [Rob Kendrick][] wrote `lua-scrypt` back when there wasn't a shared
+library for the scrypt algorithm.  The returned values were binary and a bit
+messy, and as such they are not supported by this version of the library.
+
+[libscrypt]: https://github.com/technion/libscrypt
+[Rob Kendrick]: http://www.rjek.com/
diff --git a/config.ld b/config.ld
new file mode 100644
index 0000000..50766d3
--- /dev/null
+++ b/config.ld
@@ -0,0 +1,6 @@
+file = {"luascrypt.c.ldoc"}
+readme = "README"
+format = "lua-markdown"
+project = "lua-scrypt"
+title = "lua-scrypt:  Lua binding to libscrypt"
+dir = "html"
diff --git a/luascrypt.c.ldoc b/luascrypt.c.ldoc
new file mode 100644
index 0000000..7e61b18
--- /dev/null
+++ b/luascrypt.c.ldoc
@@ -0,0 +1,54 @@
+---
+-- lua-scrypt: Bindings for libscrypt for Lua
+--
+-- lua-scrypt is a binding to libscrypt which is a password crypting and
+-- verification library.  lua-scrypt uses the libscrypt library and
+-- provides a simple interface for hashing and verifying passwords.
+-- 
+-- @module scrypt
+-- 
+
+---
+-- Take a password and return its MCF-encoded scrypted hash
+-- @function hash_password
+-- @tparam string password The password to be hashed.
+-- @tparam[opt] number N The scrypt 'N' parameter
+-- @tparam[opt] number r The scrypt 'r' parameter
+-- @tparam[opt] number p The scrypt 'p' parameter
+-- @treturn string The hashed password
+-- @raise If there is anything wrong with `N` `r` or `p` or various internal
+--        errors within libscrypt, then this function will raise an error.
+--
+-- This function takes the given password and uses the `scrypt` algorithm
+-- to hash it.  This algorithm is designed to cause difficulty in hardware
+-- accelerating cracking by chaining operations to prevent parallelism and
+-- using a non-trivial amount of RAM to make performing many separate tests
+-- too expensive to do simultanously.  To tune this, the three number
+-- parameters can be used.  `N` must be a power of two less than 65536 and
+-- is used as a general "cost" factor.  `r` is the block size factor and larger
+-- values of `r` result in more memory being used.  `p` is the parallelism
+-- factor and larger numbers simply cause the algorithm to be run more than
+-- once.
+--
+-- If omitted, `N`, `r` and `p` default to 16384, 8 and 16 respectively.  These
+-- values mean that hashing (or verifying) a password will need 16 megabytes
+-- of memory and will run at 16 iterations.  This will take around 650ms to
+-- hash a password on an i7 running around 4GHz (at the time of writing).
+--
+-- **NOTE**: Despite the function description, if you want to supply any of
+-- `N` `r` or `p` then you must provide them all.
+
+
+---
+-- Take a password hash, and a password, and verify if they match.
+-- @function verify_password
+-- @tparam string crypted The hashed password (from `crypt.hash_password`)
+-- @tparam string password The password to check against the hash.
+-- @treturn boolean True if they match, otherwise false.
+-- @raise If the hash is malformed then an error will be raised.
+--
+-- This function takes the given hash and password and checks them against
+-- one another.  The `N` `r` and `p` parameters to the hashing are included
+-- in the hashed password and have the same effect on verification as they did
+-- on creation.
+