bbop-core - npm Package Compare versions

Comparing version 0.0.3 to 0.0.4

gulpfile.js

@@ -12,6 +12,9 @@ ////
 var bump = require('gulp-bump');
+var del = require('del');
 
 var paths = {
+    readme: ['./README.md'],
     tests: ['tests/*.test.js', 'tests/*.tests.js'],
-    docable: ['lib/*.js']
+    docable: ['lib/*.js', './README.md'],
+    transients:['./doc/*', '!./doc/README.org']
 };
@@ -29,5 +32,11 @@
 // Build docs directory with JSDoc.
-gulp.task('doc', function() {
-    gulp.src(paths.docable)
+//gulp.task('doc', ['md-to-org', 'jsdoc']);
+gulp.task('doc', ['jsdoc']);
+
+// Build docs directory with JSDoc.
+// Completely dependent on clean before running doc.
+gulp.task('jsdoc', ['clean'], function(cb) {
+    gulp.src(paths.docable, paths.readme)
         .pipe(jsdoc('./doc'));
+    cb(null);
 });
@@ -37,3 +46,4 @@
 gulp.task('clean', function(cb) {
-    del(['./doc/*', '!./doc/README.org']);
+    del(paths.transients);
+    cb(null);
 });
@@ -83,2 +93,8 @@
 
+// Rerun doc build when a file changes.
+gulp.task('watch-doc', function() {
+  gulp.watch(paths.docable, ['doc']);
+  gulp.watch(paths.readme, ['doc']);
+});
+
 // The default task (called when you run `gulp` from cli)
@@ -85,0 +101,0 @@ //gulp.task('default', ['watch', 'scripts', 'images']);

lib/core.js

@@ -15,2 +15,11 @@ /**
 
+/**
+ * Return the best guess (true/false) for whether or not a given
+ * object is being used as a hash.
+ *
+ * @function
+ * @name module:bbop-core#is_hash
+ * @param {} in_thing - the thing in question
+ * @returns {boolean} boolean
+ */
 function _is_hash(in_thing){
@@ -26,2 +35,13 @@ var retval = false;
 
+/**
+ * Return the string best guess for what the input is, null if it
+ * can't be identified. In addition to the _is_a property convention,
+ * current core output strings are: 'null', 'array', 'boolean',
+ * 'number', 'string', 'function', and 'object'.
+ * 
+ * @function
+ * @name module:bbop-core#what_is
+ * @param {any} in_thing - the thing in question
+ * @returns {string} string
+ */
 function _what_is(in_thing){
@@ -54,2 +74,13 @@ var retval = null;
 
+/**
+ * Dump an object to a string form as best as possible. More meant for
+ * debugging. This is meant to be an Object walker. For a slightly
+ * different take (Object identification), see <to_string>.
+ *
+ * @see module:bbop-core.to_string
+ * @function
+ * @name module:bbop-core#dump
+ * @param {} in_thing - something
+ * @returns {string} string
+ */
 function _dump(thing){
@@ -95,2 +126,10 @@
 
+/**
+ * (Deep) clone an object down to its atoms.
+ *
+ * @function
+ * @name module:bbop-core#clone
+ * @param {any} thing - whatever
+ * @returns {any} a new whatever
+ */
 function _clone(thing){
@@ -140,2 +179,16 @@
 
+/**
+ * Attempt to return a two part split on the first occurrence of a
+ * character.
+ *
+ * Returns '' for parts not found.
+ * 
+ * Unit tests make the edge cases clear.
+ * 
+ * @function
+ * @name module:bbop-core#first_split
+ * @param {String} character - the character to split on
+ * @param {String} string - the string to split
+ * @returns {Array} list of first and second parts
+ */
 function _first_split(character, string){
@@ -162,13 +215,18 @@
 
+    clone: _clone,
+    dump: _dump,
+    first_split: _first_split,
+    is_hash: _is_hash,
+    what_is: _what_is,
+
     /**
-     * Function: crop
-     *
      * Crop a string nicely.
      * 
+     * Returns: Nothing. Side-effects: throws an error if the namespace
+     * defined by the strings is not currently found.
+     * 
      * @param {} str - the string to crop
      * @param {} lim - the final length to crop to (optional, defaults to 10)
      * @param {} suff - the string to add to the end (optional, defaults to '')
-     * 
-     * Returns: Nothing. Side-effects: throws an error if the namespace
-     * defined by the strings is not currently found.
+     * @returns {string} cropped string
      */
@@ -191,4 +249,2 @@ crop: function(str, lim, suff){
     /**
-     * Function: fold
-     *
      * Fold a pair of hashes together, using the first one as an initial
@@ -201,8 +257,6 @@ * template--only the keys in the default hash will be defined in the
      * 
-     * @param {} default_hash - Template hash.
-     * @param {} arg_hash - Argument hash to match.
-     * 
-     * Returns: A new hash.
-     * 
-     * Also see: <merge>
+     * @see module:bbop-core.merge
+     * @param {object} default_hash - Template hash.
+     * @param {object} arg_hash - Argument hash to match.
+     * @returns {object} a new hash
      */
@@ -226,13 +280,9 @@ fold: function(default_hash, arg_hash){
     /**
-     * Function: merge
-     *
      * Merge a pair of hashes together, the second hash getting
      * precedence. This is a superset of the keys both hashes.
      * 
+     * @see module:bbop-core.fold
      * @param {} older_hash - first pass
      * @param {} newer_hash - second pass
-     * 
-     * Returns: A new hash.
-     * 
-     * Also see: <fold>
+     * @returns {object} a new hash
      */
@@ -254,9 +304,6 @@ merge: function(older_hash, newer_hash){
     /**
-     * Function: get_keys
-     *
      * Get the hash keys from a hash/object, return as an array.
      *
      * @param {} arg_hash - the hash in question
-     *
-     * Returns: an array of keys
+     * @returns {Array} an array of keys
      */
@@ -277,4 +324,2 @@ get_keys: function(arg_hash){
     /**
-     * Function: hashify
-     *
      * Returns a hash form of the argument array/list. For example ['a',
@@ -285,5 +330,4 @@ * 'b'] would become {'a': true, 'b': true} or [['a', '12'], ['b',
      *
-     * @param {} list - the list to convert
-     *
-     * Returns: a hash
+     * @param {Array} list - the list to convert
+     * @returns {object} a hash
      */
@@ -313,4 +357,2 @@ hashify: function(list){
     // /**
-    //  * Function: is_same
-    //  *
     //  * Returns true if it things the two incoming arguments are value-wise
@@ -389,18 +431,2 @@ //  * the same.
     /**
-     * Function: what_is
-     *
-     * Return the string best guess for what the input is, null if it
-     * can't be identified. In addition to the _is_a property convention,
-     * current core output strings are: 'null', 'array', 'boolean',
-     * 'number', 'string', 'function', and 'object'.
-     * 
-     * @param {} in_thing - the thing in question
-     *
-     * Returns: a string
-     */
-    what_is: _what_is,
-
-    /**
-     * Function: is_array
-     *
      * Return the best guess (true/false) for whether or not a given
@@ -410,4 +436,3 @@ * object is being used as an array.
      * @param {} in_thing - the thing in question
-     *
-     * Returns: boolean
+     * @returns {boolean} boolean
      */
@@ -424,16 +449,2 @@ is_array: function(in_thing){
     /**
-     * Function: is_hash
-     *
-     * Return the best guess (true/false) for whether or not a given
-     * object is being used as a hash.
-     *
-     * @param {} in_thing - the thing in question
-     *
-     * Returns: boolean
-     */
-    is_hash: _is_hash,
-
-    /**
-     * Function: is_empty
-     *
      * Return true/false on whether or not the object in question has any
@@ -443,4 +454,3 @@ * items of interest (iterable?).
      * @param {} in_thing - the thing in question
-     *
-     * Returns: boolean
+     * @returns {boolean} boolean
      */
@@ -467,9 +477,6 @@ is_empty: function(in_thing){
     /**
-     * Function: is_defined
-     *
      * Return true/false on whether or not the passed object is defined.
      *
      * @param {} in_thing - the thing in question
-     *
-     * Returns: boolean
+     * @returns {boolean} boolean
      */
@@ -485,4 +492,2 @@ is_defined: function(in_thing){
     /**
-     * Function: pare
-     *
      * Take an array or hash and pare it down using a couple of functions
@@ -496,9 +501,6 @@ * to what we want.
      *
-     * @param {} in_thing - hash or array
-     * @param {} filter_function - hash (function(key, val)) or array (function(item, i)).
-     * @param {}  This function must return boolean true or false.
-     * @param {} sort_function - function to apply to elements: function(a, b)
-     * @param {}  This function must return an integer as the usual sort functions do.
-     *
-     * Returns: An array.
+     * @param {Array|Object} in_thing - hash or array
+     * @param {Function} filter_function - hash (function(key, val)) or array (function(item, i)); this function must return boolean true or false.
+     * @param {Function} sort_function - function to apply to elements: function(a, b); this function must return an integer as the usual sort functions do.
+     * @returns {Array} array
      */
@@ -556,15 +558,2 @@ pare: function(in_thing, filter_function, sort_function){
     /**
-     * Function: clone
-     *
-     * Clone an object down to its atoms.
-     *
-     * @param {} thing - whatever
-     *
-     * Returns: a new whatever
-     */
-    clone: _clone,
-
-    /**
-     * Function: to_string
-     *
      * Essentially add standard 'to string' interface to the string class
@@ -575,7 +564,5 @@ * and as a stringifier interface to other classes. More meant for
      *
-     * @param {} in_thing - something
-     *
-     * Returns: string
-     * 
-     * Also See: <dump>
+     * @see module:bbop-core.dump
+     * @param {any} in_thing - something
+     * @returns {string} string
      */
@@ -609,19 +596,2 @@ to_string: function(in_thing){
     /**
-     * Function: dump
-     *
-     * Dump an object to a string form as best as possible. More meant for
-     * debugging. This is meant to be an Object walker. For a slightly
-     * different take (Object identification), see <to_string>.
-     *
-     * @param {} in_thing - something
-     *
-     * Returns: string
-     * 
-     * Also See: <to_string>
-     */
-    dump: _dump,
-
-    /**
-     * Function: has_interface
-     *
      * Check to see if all top-level objects in a namespace supply an
@@ -632,9 +602,8 @@ * "interface".
      *
+     * TODO: Unit test this to make sure it catches both prototype (okay I
+     * think) and uninstantiated objects (harder/impossible?).
+     *
      * @param {} iobj - the object/constructor in question
      * @param {} interface_list - the list of interfaces (as a strings) we're looking for
-     *
-     * Returns: boolean
-     *
-     * TODO: Unit test this to make sure it catches both prototype (okay I
-     * think) and uninstantiated objects (harder/impossible?).
+     * @returns {boolean} boolean
      */
@@ -657,4 +626,2 @@ has_interface: function(iobj, interface_list){
     /**
-     * Function: get_assemble
-     *
      * Assemble an object into a GET-like query. You probably want to see
@@ -673,4 +640,3 @@ * the tests to get an idea of what this is doing.
      * @param {} qargs - hash/object
-     *
-     * Returns: string
+     * @returns {string} string
      */
@@ -770,4 +736,2 @@ get_assemble: function(qargs){
     /**
-     * Function: randomness
-     *
      * Random number generator of fixed length. Return a random number
@@ -777,4 +741,3 @@ * string of length len.
      * @param {} len - the number of random character to return.
-     *
-     * Returns: string
+     * @returns {string} string
      */
@@ -798,22 +761,2 @@ randomness: function(len){
     /**
-     * Function: first_split
-     *
-     * Attempt to return a two part split on the first occurrence of a
-     * character.
-     *
-     * Returns '' for parts not found.
-     * 
-     * Unit tests make the edge cases clear.
-     * 
-     * @param {} character - the character to split on
-     * @param {} string - the string to split
-     *
-     * Returns:
-     * @param {} list of first and second parts
-     */
-    first_split: _first_split,
-
-    /**
-     * Function: url_parameters
-     *
      * Return the parameters part of a URL.
@@ -824,5 +767,3 @@ *
      * @param {} url - url (or similar string)
-     *
-     * Returns:
-     *  list of part lists
+     * @returns {Array} list of part lists
      */
@@ -858,4 +799,2 @@ url_parameters: function(url){
     /**
-     * Function: resourcify
-     *
      * Convert a string into something consistent for urls (getting icons,
@@ -868,5 +807,3 @@ * etc.). Return a munged/hashed-down version of the resource.
      * @param {} extension - *[optional]* the extension of the resource
-     *
-     * Returns:
-     *  string
+     * @returns {string} string
      */
@@ -888,9 +825,6 @@ resourcify: function(base, resource, extension){
     /**
-     * Function: uuid
-     *
      * RFC 4122 v4 compliant UUID generator.
      * From: http://stackoverflow.com/questions/105034/how-to-create-a-guid-uuid-in-javascript/2117523#2117523
      *
-     * Returns:
-     *  string
+     * @returns {string} string
      */
@@ -909,4 +843,2 @@ uuid: function(){
     /**
-     * Function: numeric_sort_ascending
-     *
      * A sort function to put numbers in ascending order.
@@ -918,7 +850,5 @@ *
      * 
-     * @param {} a - the first number
-     * @param {} b - the second number
-     *
-     * Returns:
-     *  number of their relative worth
+     * @param {number} a - the first number
+     * @param {number} b - the second number
+     * @returns {number} number of their relative worth
      */
@@ -930,4 +860,2 @@ numeric_sort_ascending: function(a, b){
     /**
-     * Function: numeric_sort_descending
-     *
      * A sort function to put numbers in descending order.
@@ -939,7 +867,5 @@ *
      * 
-     * @param {} a - the first number
-     * @param {} b - the second number
-     *
-     * Returns:
-     *  number of their relative worth
+     * @param {number} a - the first number
+     * @param {number} b - the second number
+     * @returns {number} number of their relative worth
      */
@@ -951,10 +877,6 @@ numeric_sort_descending: function(a, b){
     /**
-     * Function: dequote
-     *
      * Remove the quotes from a string.
      * 
-     * @param {} str - the string to dequote
-     *
-     * Returns:
-     *  the dequoted string (or the original string)
+     * @param {string} str - the string to dequote
+     * @returns {string} the dequoted string (or the original string)
      */
@@ -975,4 +897,2 @@ dequote: function(str){
     /**
-     * Function: ensure
-     *
      * Make sure that a substring exists at the beginning or end (or both)
@@ -984,5 +904,3 @@ * of a string.
      * @param {} place - *[optional]* "front"|"back", place to ensure (defaults to both)
-     *
-     * Returns:
-     *  a new string with the property enforced
+     * @returns {string} a new string with the property enforced
      */
@@ -1034,11 +952,7 @@ ensure: function(str, add, place){
     /**
-     * Function: chomp
-     *
      * Trim the leading and trailing whitespace from a string.
      * Named differently so as not to confuse with JS 1.8.1's trim().
      * 
-     * @param {} str - the string to ensure that has the property
-     *
-     * Returns:
-     *  the trimmed string
+     * @param {string} str - the string to ensure that has the property
+     * @returns {string} the trimmed string
      */
@@ -1056,4 +970,2 @@ chomp: function(str){
     /**
-     * Function: splode
-     *
      * Break apart a string on certain delimiter.
@@ -1064,4 +976,3 @@ *
      *
-     * Returns:
-     *  a list of separated substrings
+     * @returns {Array} a list of separated substrings
      */
@@ -1086,4 +997,2 @@ splode: function(str, delimiter){
     // /**
-    //  * Function: evaluate
-    //  * 
     //  * Getting a cross-platform that can evaluate to the global namespace
@@ -1159,4 +1068,2 @@ //  * seems a little bit problematic. This is an attempt to wrap that all
     /**
-     * Function: extend
-     * 
      * What seems to be a typical idiom for subclassing in JavaScript.
@@ -1174,5 +1081,2 @@ *
      * @param {} superclass - the superclass object
-     * 
-     * Returns:
-     *  n/a
      */
@@ -1208,4 +1112,2 @@ extend: function(subclass, baseclass){
     /**
-     * Constructor: logger
-     * 
      * BBOP JS logger object. Using .kvetch(), you can automatically log a
@@ -1219,3 +1121,3 @@ * message in almost any environment you find yourself in--browser,
      *
-     * 
+     * @constructor
      * @param {string} initial_context - (optional) initial context as string.
@@ -1226,6 +1128,6 @@ */
 	/**
-	 * Variable: DEBUG 
-	 * 
 	 * Different debugging available per object. Externally toggle
 	 * between true and false to switch on and off the logging.
+	 *
+	 * @variable {boolean}
 	 */
@@ -1243,7 +1145,5 @@ this.DEBUG = false;
 	/**
-	 * Function: reset_context
-	 * 
 	 * Define the ability to reset the contex.
 	 * 
-	 * @param {string} new_initial_context - (optional) New context to start with.
+	 * @param {string} new_initial_context - (optional) new context to start with
 	 */
@@ -1259,9 +1159,5 @@ this.reset_context = function(new_initial_context){
 	/**
-	 * Function: push_context
-	 * 
 	 * Add an additional logging context to the stack.
 	 * 
-	 * Arguments:
 	 * @param {string} new_context - New context to add to the context stack.
-	 *  
 	 */
@@ -1273,4 +1169,2 @@ this.push_context = function(new_context){
 	/**
-	 * Function: pop_context
-	 * 
 	 * Remove the last context if it's there.
@@ -1337,10 +1231,7 @@ */
 	/**
-	 * Function: kvetch
-	 * 
 	 * Log a string to somewhere. Also return a string to (mostly for
 	 * the unit tests).
 	 * 
-	 * Arguments:
-	 * @param {string} initial_context - (optional) initial context as string.
-	 *  string - The string to print out to wherever we found.
+	 * @param {string} initial_context - (optional) initial context as string
+	 * @returns {string} string to print out to wherever we found
 	 */
@@ -1347,0 +1238,0 @@ this.kvetch = function(string){

package.json

 {
     "name": "bbop-core",
-    "version": "0.0.3",
-    "license": "BSD",
+    "version": "0.0.4",
+    "license": "BSD-3-Clause",
     "description": "A set of useful and common JavaScript functions to supplement other more basic utility libraries.",
@@ -6,0 +6,0 @@ "keywords": [

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Misc. License Issues

License

(Experimental) A package's licensing information has fine-grained problems.

Found 1 instance in 1 package

Improved metrics

Number of medium license alerts

0

decreased by-100%

Number of lines in readme file

8

increased by166.67%

Worsened metrics

Total package byte prevSize

73483

decreased by-0.71%

Lines of code

2041

decreased by-4.27%

No dependency changes