Improve documentation

.gitignore

@@ -1,3 +1,3 @@
 node_modules
-coverage
-npm-debug.log
+npm-debug.log
+.nyc_output

.travis.yml

@@ -1,6 +1,9 @@
 language: node_js
 node_js:
-  - "0.11"
-  - "0.10"
+  - "node"
+  - "iojs"
+  - "4"
 
-after_script: NODE_ENV=test istanbul cover ./node_modules/mocha/bin/_mocha --report lcovonly -- -R spec && cat ./coverage/lcov.info | ./node_modules/coveralls/bin/coveralls.js && rm -rf ./coverage
+install: make clean build
+script: make test
+after_success: make coverage

GLOSSARY.md

@@ -0,0 +1,11 @@
+# Logically true
+
+A value is said to be logically true, if it's not strictly equal to `false`, `null`, or `undefined`.
+
+# Logically false
+
+A value is said to be logically false, if it's stricly equal to `false`, `null`, or `undefined`.
+
+# Variadic
+
+A variadic function takes a variable number of arguments. It may or may not have required arguments, which will precede a variable length list of arguments.

Makefile

@@ -0,0 +1,36 @@
+PATH  := node_modules/.bin:$(PATH)
+SHELL := /bin/bash
+
+SRC = $(wildcard src/*.js)
+LIB = $(SRC:src/%.js=lib/%.js)
+TST = $(wildcard test/*.js) $(wildcard test/**/*.js)
+NPM = @npm install --local > /dev/null && touch node_modules
+
+v  ?= patch
+
+node_modules: package.json
+	$(NPM)
+node_modules/%:
+	$(NPM)
+
+test: node_modules
+	@mocha $(TST)
+
+.nyc_output: node_modules
+	@nyc $(MAKE) test
+
+coverage: .nyc_output
+	@nyc report --reporter=text-lcov | coveralls
+
+dev: node_modules
+	@nodemon -q -x "(clear; nyc $(MAKE) test && nyc report) || true"
+
+release: clean node_modules test
+	@npm version $(v)
+	@npm publish
+	@git push --follow-tags
+
+clean:
+	@rm -rf $$(cat .gitignore)
+
+.PHONY: test coverage dev release clean

README.md

@@ -1,13 +1,48 @@
 ![Funkis](https://raw.githubusercontent.com/mstade/funkis/master/logo.png)
 
+Funkis
+======
+
 This library aims to be a fully fledged environment for functional programming in JavaScript. It provides a number of functions common to functional programming, ranging from low-level constructs to high-level abstractions.
 
-Funkis is work in progress, and APIs change quickly while the library is still being developed. Please don't use it for anything, or at least do so at your own risk. Beyond the [tests][1] there is no documentation available – good luck!
+Funkis is work in progress, and APIs change quickly while the library is still being developed. Please don't use it for anything, or at least do so at your own risk.
+
+Usage
+-----
+
+Get funkis from npm:
+
+```bash
+npm install --save funkis
+```
+
+Once installed as a dependency, it is possible to use funkis through the kitchen sink object that holds a reference to all funkis functions:
+
+```javascript
+var f = require('funkis')
+
+f.and(1, 2, 3) // 3
+```
 
-[1]: test
+Or, if you'd rather, you can depend on the functions directly:
+
+```javascript
+var and = require('funkis/lib/and')
+
+and(1, 2, 3) // 3
+```
+
+Further documentation is available in the [online manual], or the [man] folder.
+
+[man]: man
+[online manual]: http://madebystade.com/funkis/
 
 Status
 ------
 
 [![Build Status](http://img.shields.io/travis/mstade/funkis.svg?style=flat-square)](https://travis-ci.org/mstade/funkis)
 [![Coverage Status](http://img.shields.io/coveralls/mstade/funkis.svg?style=flat-square)](https://coveralls.io/r/mstade/funkis?branch=master)
+
+---
+
+[LICENSE](LICENSE)

SUMMARY.md

@@ -0,0 +1,8 @@
+# Summary
+
+- API reference
+  - [and](man/and.md)
+  - [apply](man/apply.md)
+  - [assert](man/assert.md)
+  - [call](man/call.md)
+  - [compose](man/compose.md)

man/and.md

@@ -0,0 +1,3 @@
+# and
+
+If every given value is logically true, `and` returns the last value; otherwise it returns the first value that was logically false. If a given value is a function, the function will be called with no arguments, and the return value will be used for the test.

man/apply.md

@@ -0,0 +1,7 @@
+# apply
+
+When given a single argument `fn`, `apply` will call `fn` with no arguments and return its value.
+
+When given the argument `fn` and an array `args`, then the values in `args` will be passed to `fn` when it is called.
+
+The value of `this` will be bound to whatever the value of `this` is when `apply` is called. Thus, `apply.bind(obj)(fn)` would bind `fn` to `obj`, unless `fn` has already been bound.

man/assert.md

@@ -0,0 +1,3 @@
+# assert
+
+If the first argument `x` passed to `assert` is logically true, the value of `x` is returned. If however, the value of `x` is logically false then `assert` will throw an error. If provided with a second parameter `message`, the thrown error will carry that message. If `message` is an actual `Error` instance, it will be thrown without modification.

man/call.md

@@ -0,0 +1,3 @@
+# call
+
+The same as [apply](./apply.md), with the notable difference that `call` is variadic. Otherwise the exact same functionality.

man/compose.md

@@ -0,0 +1,3 @@
+# compose
+
+Returns a composition `fn` of the given functions; that is, a new function which composes all given functions. When called with any number of arguments, `fn` will apply those arguments to the rightmost function given in the composition, whose result will then be applied to the next rightmost function. This process repeats until all functions in the composition have been applied.

package.json

@@ -3,18 +3,17 @@
   "version": "0.2.0",
   "description": "Functional programming in JavaScript.",
   "main": "index.js",
-  "scripts": {
-    "test": "istanbul test ./node_modules/mocha/bin/_mocha --report html -- -R spec"
-  },
-  "author": "Marcus Stade",
+  "author": "Marcus Stade <[email protected]> (http://madebystade.se)",
   "license": "MIT",
   "devDependencies": {
-    "coveralls": "~2.8.0",
-    "expect.js": "^0.3.1",
-    "istanbul": "~0.2.4",
-    "mocha": "~1.17.1",
+    "coveralls": "2.8.0",
+    "expect.js": "0.3.1",
+    "gitbook-cli": "0.3.6",
+    "mocha": "1.17.1",
     "mocha-lcov-reporter": "0.0.1",
-    "must": "git://github.com/mstade/js-must#throw-error-instance"
+    "must": "git://github.com/mstade/js-must#throw-error-instance",
+    "nodemon": "1.7.1",
+    "nyc": "3.2.2"
   },
   "repository": {
     "type": "git",

test/man.js

@@ -0,0 +1,21 @@
+const expect = require('must')
+    , each   = require('../lib/each')
+    , path   = require('path')
+    , fs     = require('fs')
+    , $      = require('../lib/partial')
+
+describe('documentation', function() {
+  it('should exist for all functions', function() {
+    var names = fs.readdirSync(path.join(__dirname, '../lib')).map(function(file) {
+      return path.basename(file, '.js')
+    })
+
+    each(names, function(name) {
+      try {
+        fs.accessSync(__dirname + '/../man/' + name + '.md')
+      } catch (e) {
+        throw new Error('No documentation for function `' + name + '` found!')
+      }
+    })
+  })
+})