funcdef: Function Definition Generation for StdLib

funcdef is a documentation generator for StdLib
services, created using the lib command line
tools.

funcdef performs static analysis to;

- make sure files are exporting a single function
- make sure these functions have the correct footprint, for example, if
a function is not async, it should accept a callback as the last parameter
- ensure that documentation of these functions is correct, using the
@param and @return blocks of JSDoc
- enforce type safety in function parameters where applicable (default values
should match documented types and vice-versa)

Example

funcdef reads a file called myFunction.js;

``javascript
/**
* This is my function, it likes the greek alphabet
* @param {String} alpha Some letters, I guess
* @param {Number} beta And a number
* @param {Boolean} gamma True or false?
* @return {Object} some value
*/
module.exports = async function(alpha, beta = 2, gamma) {
/ your code /
};
`

and outputs an Object:

`json
{
"name": "myFunction",
"pathname": "myFunction.js",
"description": "This is my function, it likes the greek alphabet",
"context": null,
"params": [
{
"name": "alpha",
"type": "string",
"description": "Some letters, I guess"
},
{
"name": "beta",
"type": "number",
"defaultValue": 2,
"description": "And a number"
},
{
"name": "gamma",
"type": "boolean",
"description": "True or false?"
}
],
"returns": {
"type": "object",
"description": "some value"
}
}
`

Rules (Node.js)

- All files that are children of a parsed folder must export a valid function
with module.exports = in the top node of the file's syntax tree
- There are two magic parameter names, context and callback, these parameters
are ignored as params
- context and callback parameters must be the last one or two arguments
(in that order) when provided
- context provides access to microservice invocation details
- callback must exist if a function is not async
- The first (non-magic) parameter can not be of type any or object
(i.e. type must be defined by comments or inferred from default values)
- Function definitions (commented) must match types of default values (exception
is null defaults)
- Parameter default values must be literals and can not be computed properties
(i.e. include functions or variables)
- Destructuring assignment is not supported in function definitions
- Any file named __init__.js will use the parent directory as the function name
- Following this, naming collisions are not allowed
- Function and directory names must start with a letter (a-z) and
must be alphanumeric, with allowed symbols _ only.

Usage

Right now, funcdef is meant as a supplementary tool for building microservices
on StdLib and enforcing "convention over configuration"
development paradigms. It is MIT licensed and you're welcome to use it in
your own projects, as long as reference is made back to the original author and
Polybit Inc. / StdLib.

`javascript
const funcdef = require('funcdef');
const parser = new funcdef.FunctionParser();

// loads function definitions from ./functions
// includes 'functions/' in path name but not function name
let definitions = parser.load('.', 'functions');
`

Etc.

funcdef` is copyright 2017 Polybit Inc.