wassup-doc

wassup-doc
==========

wassup-doc is a module for documenting your programs via method chaining -- no
need for a gadget that reads your comments.

(insert obligatory bugs bunny image here)

Examples
--------
Documenting a function:

``javascript
const doc = require('wassup-doc') // munches carrot
/*
doc is a wrapper for whatever you're about to document -- mutating
Function.prototype would be bad.
*/
const abs = doc(Math.abs.bind(null))
// surprisingly, Math.abs.name is 'abs', not 'Math.abs'
.name('Math.abs')
// provide a short summary
.summarize('Returns the absolute value of an argument.')
/*
doc.prototype.desc can be used to provide a long summary if you need
one, otherwise the description will be identical to the summary.

You can also derive a summary from the description; In this case the
summary will be the first sentence of the description.
*/
// a short annotation explaining what the function takes in and spits out:
.annotate('(Number) -> Number')
// and finally we need to unwrap the value:
.value()
// the help function is case insensitive
console.log(doc.help('math.abs'))
`

help formats the output using chalk, so you'll get nice(-ish) output like this:

__Math.abs__ _(Number) -> Number_

=======================

Returns the absolute value of an argument.

There's also a nice function for making sure the outputs from your higher-order functions get reasonable names:

`javascript
const {higherOrder, rename} = require('wassup-doc')
/*
We need to provide an explicit name because JavaScript has trouble deriving
names from higher-order functions...

...but luckily we have an optional second argument for that.
*/
const flip = higherOrder(
f => (x, y) => f(y, x)
,'flip'
)
const append = (x, y) => x + y
// what would you call it? :>
const flappend = flip(append)
console.log(flappend.name)
// ^ 'flip(append)' -- it would have been '' if it weren't for higherOrder
console.log(flappend('trains', 'i like ')) // 'i like trains'

// a hopelessly overspecialized curry function
const curry3 = higherOrder(
f => (...xs) => xs.length === 3
? f(...xs)
: xs.length === 2
? y => f(...xs, y)
: (...ys) => ys.length === 2 ? f(...xs, ...ys) : z => f(...xs, ...ys, z)
,'curry3'
)

const tern = rename(curry3((cond, x, y) => cond ? x() : y()), 'curry3')
const always = tern(true)
// ^ also known as const (hello haskellers ^^)
console.log(always.name) // 'tern(true)'
const foo = tern(true, function () {
console.log('Laziness is nice but I\'m going off-topic so this example is getting hopelessly long.')
return 'You shouldn\'t put side effects in some places.'
})
console.log(foo.name) // 'tern(true,anonymous)'
`

Features
--------

- 4/10 quality
- Simple
- Hasn't been voted "crummiest module ever" (so far)
- Dynamic (as in stuff gets documented at runtime)

Installation
------------

Just type

npm install project`

and enjoy knowing what your functions do!

Contribute
----------

- Issues
- Source

License
-------

The project is licensed under the MIT license.