Please use JSDoc format for all function descriptions: http://usejsdoc.org/

all params, returns and throws should here with type and short descriptions