README

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:

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:

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

License

The project is licensed under the MIT license.

Usage no npm install needed!