list: comments.

lib/utils/list.js

@@ -1,11 +1,20 @@
+/*!
+ * list.js - double linked list for bcoin
+ * Copyright (c) 2014-2016, Christopher Jeffrey (MIT License).
+ * https://github.com/bcoin-org/bcoin
+ */
+
 'use strict';
 
 var assert = require('assert');
 
 /**
- * A linked list.
+ * A double linked list.
  * @exports List
  * @constructor
+ * @property {ListItem|null} head
+ * @property {ListItem|null} tail
+ * @property {Number} size
  */
 
 function List() {
@@ -39,6 +48,7 @@ List.prototype.reset = function reset() {
 
 /**
  * Remove the first item in the list.
+ * @returns {ListItem}
  */
 
 List.prototype.shift = function shift() {
@@ -54,8 +64,8 @@ List.prototype.shift = function shift() {
 
 /**
  * Prepend an item to the linked list (sets new head).
- * @private
  * @param {ListItem}
+ * @returns {Boolean}
  */
 
 List.prototype.unshift = function unshift(item) {
@@ -64,8 +74,8 @@ List.prototype.unshift = function unshift(item) {
 
 /**
  * Append an item to the linked list (sets new tail).
- * @private
  * @param {ListItem}
+ * @returns {Boolean}
  */
 
 List.prototype.push = function push(item) {
@@ -74,6 +84,7 @@ List.prototype.push = function push(item) {
 
 /**
  * Remove the last item in the list.
+ * @returns {ListItem}
  */
 
 List.prototype.pop = function pop() {
@@ -92,6 +103,7 @@ List.prototype.pop = function pop() {
  * @private
  * @param {ListItem|null} ref
  * @param {ListItem} item
+ * @returns {Boolean}
  */
 
 List.prototype.insert = function insert(ref, item) {
@@ -130,6 +142,7 @@ List.prototype.insert = function insert(ref, item) {
  * Remove item from the linked list.
  * @private
  * @param {ListItem}
+ * @returns {Boolean}
  */
 
 List.prototype.remove = function remove(item) {
@@ -164,8 +177,9 @@ List.prototype.remove = function remove(item) {
 
 /**
  * Slice the list to an array of items.
- * @param {Number} total
- * @returns {Object[]}
+ * Will remove the items sliced.
+ * @param {Number?} total
+ * @returns {ListItem[]}
  */
 
 List.prototype.slice = function slice(total) {
@@ -201,7 +215,7 @@ List.prototype.slice = function slice(total) {
 
 /**
  * Convert the list to an array of items.
- * @returns {Object[]}
+ * @returns {ListItem[]}
  */
 
 List.prototype.toArray = function toArray() {
@@ -215,7 +229,7 @@ List.prototype.toArray = function toArray() {
 };
 
 /**
- * Represents an LRU item.
+ * Represents an linked list item.
  * @constructor
  * @private
  * @param {String} key