Added API annotations for internal functions

Author: BasicPrimitives

src.primitives/algorithms/LinkedHashItems.js

@@ -1,10 +1,19 @@
-primitives.common.LinkedHashItems = function () {
+/**
+ * Creates linked hash list collection.
+ * @returns {LinkedHashItems} Returns linked hash list structure
+ */
+primitives.common.LinkedHashItems = function () {
   var segmentsHash = {},
     nextKeys = {},
     prevKeys = {},
     startSegmentKey = null,
     endSegmentKey = null;
 
+  /**
+   * Adds new item to collection
+   * @param {string} key The new item key 
+   * @param {object} item The new item context object value
+   */
   function add(key, item) {
     if (segmentsHash.hasOwnProperty(key)) {
       throw "Duplicate segments are not supported!";
@@ -21,30 +30,70 @@
     endSegmentKey = key;
   }
 
+  /**
+   * Checks if collection is empty
+   * 
+   * @returns {boolean} Returns true if collection is empty
+   */
   function isEmpty() {
     return startSegmentKey == null;
   }
 
+  /**
+   * Item context object
+   * 
+   * @param {string} key The item's key
+   * @returns {object} Returns context object
+   */
   function item(key) {
     return segmentsHash[key];
   }
 
+  /**
+   * Gets next key
+   * 
+   * @param {string} key The item key
+   * @returns {string} Returns key of the next collection item
+   */
   function nextKey(key) {
     return nextKeys[key];
   }
 
+  /**
+   * Gets previous key
+   * 
+   * @param {string} key The item key
+   * @returns {string} Returns key of the previous collection item
+   */
   function prevKey(key) {
     return prevKeys[key];
   }
 
+  /**
+   * First collection item key
+   * 
+   * @returns {string} Returns the key of the first item in the collection
+   */
   function startKey() {
     return startSegmentKey;
   }
 
+  /**
+   * Last collection item key
+   * 
+   * @returns {string} Returns key of the last item in the collection
+   */
   function endKey() {
     return endSegmentKey;
   }
 
+   /**
+   * Adds new item to the head of the list
+   * 
+   * @param {string} key The new item key 
+   * @param {object} item The new item context object value
+   * @returns {string} Returns key of the last item in the collection
+   */ 
   function unshift(key, item) {
     if (segmentsHash.hasOwnProperty(key)) {
       throw "Duplicate segments are not supported!";
@@ -61,6 +110,13 @@
     startSegmentKey = key;
   }
 
+   /**
+   * Inserts new item into the list after the given key 
+   *  
+   * @param {string} afterKey The key that the new element is placed after 
+   * @param {string} key The new item key 
+   * @param {object} item The new item context object value
+   */ 
   function insertAfter(afterKey, key, item) {
     if (segmentsHash.hasOwnProperty(key)) {
       throw "Duplicate segments are not supported!";
@@ -82,6 +138,13 @@
     }
   }
 
+  /**
+   * Inserts new item into the list before the given key  
+   * 
+   * @param {string} beforeKey The key that the new element is placed before 
+   * @param {string} key The new item key 
+   * @param {object} item The new item context object value
+   */ 
   function insertBefore(beforeKey, key, item) {
     if (segmentsHash.hasOwnProperty(key)) {
       throw "Duplicate segments are not supported!";
@@ -97,6 +160,10 @@
     }
   }
 
+  /**
+   * Removes item
+   * @param {string} key The key of the item 
+   */
   function remove(key) {
     var prevKey = prevKeys[key],
       nextKey = nextKeys[key];
@@ -118,6 +185,9 @@
     delete prevKeys[key];
   }
 
+  /**
+   * Empties collection
+   */
   function empty() {
     segmentsHash = {};
     nextKeys = {};
@@ -152,20 +222,50 @@
     }
   }
 
+  /**
+   * Appends one list to another
+   * 
+   * @param {LinkedHashItems} list A list to append to the end of the current list  
+   */
   function attach(list) {
     list.iterate(function (segment, key) {
       add(key, segment);
     });
   }
 
+  /**
+   * Callback function for iterating list items
+   * 
+   * @callback onLinkedHashItemsCallback
+   * @param {object} item  The item context object
+   * @param {string} key The item key
+   * @returns {boolean} Returns true to break the iteration process
+   */
+
+  /**
+   * Loops items of the collection
+   * @param {onLinkedHashItemsCallback} onItem  Callback function for iterating collection items
+   * @param {string} startKey The key to start iteration from 
+   * @param {string} endKey The key to end iteration at
+   */
   function iterate(onItem, startKey, endKey) {
     _iterate(true, onItem, startKey, endKey);
   }
 
+  /**
+   * Loops items of the collection backward
+   * @param {onLinkedHashItemsCallback} onItem  Callback function for iterating collection items
+   * @param {string} startKey The key to start iteration from 
+   * @param {string} endKey The key to end iteration at
+   */
   function iterateBack(onItem, startKey, endKey) {
     _iterate(false, onItem, startKey, endKey);
   }
 
+  /**
+   * Validates internal data consistensy of the structure
+   * @returns {boolean} Returns true if it pass validation
+   */
   function validate(info) {
     var key, prevKey, nextKey;
     for (key in segmentsHash) {
@@ -221,6 +321,11 @@
     return true;
   }
 
+  /**
+   * Returns a regular javascript array of collection items
+   * 
+   * @returns{object[]} Returns array containing items of the collection
+   */
   function toArray() {
     var result = [];
 

src.primitives/algorithms/RMQ.js

@@ -1,4 +1,10 @@
-primitives.common.RMQ = function (items) {
+/**
+ * Creates range minimum query structure
+ * 
+ * @params {number[]} items Collection of numbers
+ * @returns {rmq} Returns range minimum query structure
+ */
+primitives.common.RMQ = function (items) {
 	var _lookup = [];
 	var _log2 = Math.log(2);
 
@@ -21,6 +27,12 @@
 		}
 	}
 
+	/**
+	 * Returns index of minimum item for the given range of items
+	 * @param {number} from The left margin index
+	 * @param {number} to The right margin index
+	 * @returns {number} Returns index of the minimum item
+	 */
 	function getRangeMinimumIndex(from, to) {
 		var power = Math.floor(Math.log(to - from + 1) / _log2);
 
@@ -31,6 +43,12 @@
 		}
 	}
 
+	/**
+	 * Return minimum value for the given range
+	 * @param {number} from The left index of the range
+	 * @param {number} to The right index of the range
+	 * @returns {number} Returns minimum value in the range
+	 */
 	function getRangeMinimum(from, to) {
 		return items[getRangeMinimumIndex(from, to)];
 	}

src.primitives/algorithms/SortedList.js

@@ -1,3 +1,7 @@
+/**
+ * Creates self-balancing binary search tree structure.
+ * @returns {SortedList} Returns sorted list collection. 
+ */
 primitives.common.SortedList = function () {
   var _rootNode = null;
 
@@ -117,6 +121,20 @@ primitives.common.SortedList = function () {
     }
   }
 
+  /**
+   * Callback function to notify about duplicate values
+   * 
+   * @callback onSortedListDuplicateCallback
+   * @param {objct} context The context object of the duplicate value
+   */
+
+  /**
+   * Adds value to sorted list collection
+   * @param {number} value The value 
+   * @param {object} context The value context object
+   * @param {object} thisArg The callback function invocation context 
+   * @param {onSortedListDuplicateCallback} onDuplicate Callback function for duplicates values notification
+   */
   function add(value, context, thisArg, onDuplicate) {
     if (_rootNode == null) {
       _rootNode = new Node(value, context);
@@ -211,6 +229,10 @@ primitives.common.SortedList = function () {
     toNode.context = fromNode.context;
   }
 
+  /**
+   * Removes value from the sorted list
+   * @param {number} value The removed value 
+   */
   function remove(value) {
     var trace = [];
     var node = _rootNode;
@@ -273,6 +295,11 @@ primitives.common.SortedList = function () {
     }
   }
 
+  /**
+   * Returns context object of the next value following the given one
+   * @param {number} fromValue The value to start search from
+   * @returns {object} Returns context object of the first value in sorted list greater than the start value.
+   */
   function nextContext(fromValue) {
     var result = null;
     loopForward(this, fromValue, function (value, context) {
@@ -282,6 +309,21 @@ primitives.common.SortedList = function () {
     return result;
   }
 
+  /**
+   * Callback function for iterating values of the sorted list
+   * 
+   * @callback onSortedListItemCallback
+   * @param {number} value The value
+   * @param {object} context The value context object
+   * @returns {boolean} Returns true to break loop operation  
+   */
+
+  /**
+   * Loops sorted list values
+   * @param {object} thisArg The callback function invocation context 
+   * @param {number} fromValue The start value to loop items of sorted list
+   * @param {onSortedListItemCallback} onItem Callback function to iterate over sorted list values
+   */
   function loopForward(thisArg, fromValue, onItem) { //function onItem(value, context)
     if (onItem != null) {
       var trace = [];
@@ -317,6 +359,11 @@ primitives.common.SortedList = function () {
     }
   }
 
+  /**
+   * Returns context object of the previous value preceding the given one
+   * @param {number} fromValue The value to start search from
+   * @returns {object} Returns context object of the first value in sorted list less than the start value.
+   */
   function previousContext(fromValue) {
     var result = null;
     loopBackward(this, fromValue, function (nextValue, context) {
@@ -326,6 +373,12 @@ primitives.common.SortedList = function () {
     return result;
   }
 
+  /**
+   * Loops sorted list values backward
+   * @param {object} thisArg The callback function invocation context 
+   * @param {number} fromValue The start value to loop items of sorted list
+   * @param {onSortedListItemCallback} onItem Callback function to iterate over sorted list values
+   */
   function loopBackward(thisArg, fromValue, onItem) {
     if (onItem != null) {
       var trace = [];
@@ -388,6 +441,11 @@ primitives.common.SortedList = function () {
     return result;
   }
 
+  /**
+   * Validate internal data consistency of the self-balancing binary search tree structure
+   * 
+   * @returns {boolean} Returns true if structure pass validation
+   */
   function validate() {
     if (_rootNode != null) {
       var level = [_rootNode];