Major update to doc comment formatting for new DataTables web-site

Also correct a load of JS errors such as leaking variables and use consistent formatting.
DataTables · Jan 8, 2014 · 4f29d7f · 4f29d7f
1 parent 0ab60d1
commit 4f29d7f
Show file tree

Hide file tree

Showing 76 changed files with 1,026 additions and 498 deletions.
diff --git a/api/average().js b/api/average().js
@@ -1,6 +1,8 @@
 /**
  * Average the values in a data set.
+ *
  *  @name average()
+ *  @summary 
  *  @author [Allan Jardine](http://sprymedia.co.uk)
  *  @requires DataTables 1.10+
  *

diff --git a/api/fnAddDataAndDisplay.js b/api/fnAddDataAndDisplay.js
@@ -6,9 +6,10 @@
  * This function is a drop in replacement for fnAddData with one important
  * exception, it will only take a 1D array or an object, and not a 2D array
  * (i.e. it will not add multiple rows like fnAddData).
+ *
  *  @name fnAddDataAndDisplay
- *  @anchor fnAddDataAndDisplay
- *  @author <a href="http://sprymedia.co.uk">Allan Jardine</a>
+ *  @summary 
+ *  @author [Allan Jardine](http://sprymedia.co.uk)
  *
  *  @example
  *    $(document).ready(function() {
@@ -17,18 +18,18 @@
  *    } );
  */
 
-$.fn.dataTableExt.oApi.fnAddDataAndDisplay = function ( oSettings, aData )
+jQuery.fn.dataTableExt.oApi.fnAddDataAndDisplay = function ( oSettings, aData )
 {
 	/* Add the data */
 	var iAdded = this.oApi._fnAddData( oSettings, aData );
 	var nAdded = oSettings.aoData[ iAdded ].nTr;
-	 
+
 	/* Need to re-filter and re-sort the table to get positioning correct, not perfect
 	 * as this will actually redraw the table on screen, but the update should be so fast (and
 	 * possibly not alter what is already on display) that the user will not notice
 	 */
 	this.oApi._fnReDraw( oSettings );
-	 
+
 	/* Find it's position in the table */
 	var iPos = -1;
 	for( var i=0, iLen=oSettings.aiDisplay.length ; i<iLen ; i++ )
@@ -39,14 +40,14 @@ $.fn.dataTableExt.oApi.fnAddDataAndDisplay = function ( oSettings, aData )
 			break;
 		}
 	}
-	 
+
 	/* Get starting point, taking account of paging */
 	if( iPos >= 0 )
 	{
 		oSettings._iDisplayStart = ( Math.floor(i / oSettings._iDisplayLength) ) * oSettings._iDisplayLength;
 		this.oApi._fnCalculateEnd( oSettings );
 	}
-	 
+
 	this.oApi._fnDraw( oSettings );
 	return {
 		"nTr": nAdded,

diff --git a/api/fnAddTr.js b/api/fnAddTr.js
@@ -1,15 +1,16 @@
 /**
  * Take a TR element and add it to a DataTables table. Useful for maintaining
  * custom classes and other attributes.
+ *
  *  @name fnAddTr
- *  @anchor fnAddTr
- *  @author <a href="http://sprymedia.co.uk">Allan Jardine</a>
+ *  @summary 
+ *  @author [Allan Jardine](http://sprymedia.co.uk)
  *
  *  @example
  *    
  */
 
-$.fn.dataTableExt.oApi.fnAddTr = function ( oSettings, nTr, bRedraw ) {
+jQuery.fn.dataTableExt.oApi.fnAddTr = function ( oSettings, nTr, bRedraw ) {
     if ( typeof bRedraw == 'undefined' )
     {
         bRedraw = true;
@@ -24,7 +25,8 @@ $.fn.dataTableExt.oApi.fnAddTr = function ( oSettings, nTr, bRedraw ) {
 
     var aData = [];
     var aInvisible = [];
-    for ( var i=0 ; i<nTds.length ; i++ )
+    var i;
+    for ( i=0 ; i<nTds.length ; i++ )
     {
         aData.push( nTds[i].innerHTML );
         if (!oSettings.aoColumns[i].bVisible)
@@ -41,7 +43,7 @@ $.fn.dataTableExt.oApi.fnAddTr = function ( oSettings, nTr, bRedraw ) {
     oSettings.aiDisplay = oSettings.aiDisplayMaster.slice();
 
     // Hidding invisible columns
-    for ( var i = (aInvisible.length - 1) ; i >= 0 ; i-- )
+    for ( i = (aInvisible.length - 1) ; i >= 0 ; i-- )
     {
 		oSettings.aoData[iIndex]._anHidden[ i ] = nTds[aInvisible[i]];
 		nTr.removeChild( nTds[aInvisible[i]] );

diff --git a/api/fnColumnIndexToVisible.js b/api/fnColumnIndexToVisible.js
@@ -4,9 +4,10 @@
  * index value for the column positions. This function converts the data
  * column index (i.e. all columns regardless of visibility) into a visible
  * column index.
+ *
  *  @name fnColumnIndexToVisible
- *  @anchor fnColumnIndexToVisible
- *  @author <a href="http://sprymedia.co.uk">Allan Jardine</a>
+ *  @summary 
+ *  @author [Allan Jardine](http://sprymedia.co.uk)
  *
  *  @example
  *    

diff --git a/api/fnDataUpdate.js b/api/fnDataUpdate.js
@@ -1,18 +1,19 @@
 /**
  * Update the internal data for a TR element based on what is used in the 
  * DOM. You will likely want to call fnDraw() after this function.
+ *
  *  @name fnDataUpdate
- *  @anchor fnDataUpdate
+ *  @summary 
  *  @author Lior Gerson
  *
  *  @example
  *    
  */
 
-$.fn.dataTableExt.oApi.fnDataUpdate = function ( oSettings, nRowObject, iRowIndex )
+jQuery.fn.dataTableExt.oApi.fnDataUpdate = function ( oSettings, nRowObject, iRowIndex )
 {
-	$(nRowObject).find("TD").each( function(i) {
+	jQuery(nRowObject).find("TD").each( function(i) {
 		  var iColIndex = oSettings.oApi._fnVisibleToColumnIndex( oSettings, i );
-		  oSettings.oApi._fnSetCellData( oSettings, iRowIndex, iColIndex, $(this).html() );
+		  oSettings.oApi._fnSetCellData( oSettings, iRowIndex, iColIndex, jQuery(this).html() );
 	} );
 };
diff --git a/api/fnDisplayRow.js b/api/fnDisplayRow.js
@@ -1,8 +1,9 @@
 /**
  * Take a TR element and alter the table's paging to show the TR in question.
+ *
  *  @name fnDisplayRow
- *  @anchor fnDisplayRow
- *  @author <a href="http://sprymedia.co.uk">Allan Jardine</a>
+ *  @summary 
+ *  @author [Allan Jardine](http://sprymedia.co.uk)
  *
  *  @example
  *    $(document).ready(function() {
@@ -12,14 +13,14 @@
  *    } );
  */
 
-$.fn.dataTableExt.oApi.fnDisplayRow = function ( oSettings, nRow )
+jQuery.fn.dataTableExt.oApi.fnDisplayRow = function ( oSettings, nRow )
 {
 	// Account for the "display" all case - row is already displayed
 	if ( oSettings._iDisplayLength == -1 )
 	{
 		return;
 	}
- 
+
 	// Find the node in the table
 	var iPos = -1;
 	for( var i=0, iLen=oSettings.aiDisplay.length ; i<iLen ; i++ )
@@ -30,13 +31,13 @@ $.fn.dataTableExt.oApi.fnDisplayRow = function ( oSettings, nRow )
 			break;
 		}
 	}
-	 
+
 	// Alter the start point of the paging display
 	if( iPos >= 0 )
 	{
 		oSettings._iDisplayStart = ( Math.floor(i / oSettings._iDisplayLength) ) * oSettings._iDisplayLength;
 		this.oApi._fnCalculateEnd( oSettings );
 	}
-	 
+
 	this.oApi._fnDraw( oSettings );
 };
diff --git a/api/fnDisplayStart.js b/api/fnDisplayStart.js
@@ -1,24 +1,25 @@
 /**
  * Set the point at which DataTables will start it's display of data in the
  * table.
+ *
  *  @name fnDisplayStart
- *  @anchor fnDisplayStart
- *  @author <a href="http://sprymedia.co.uk">Allan Jardine</a>
+ *  @summary 
+ *  @author [Allan Jardine](http://sprymedia.co.uk)
  *
  *  @example
  *    
  */
 
-$.fn.dataTableExt.oApi.fnDisplayStart = function ( oSettings, iStart, bRedraw )
+jQuery.fn.dataTableExt.oApi.fnDisplayStart = function ( oSettings, iStart, bRedraw )
 {
     if ( typeof bRedraw == 'undefined' )
     {
         bRedraw = true;
     }
-     
+
     oSettings._iDisplayStart = iStart;
     oSettings.oApi._fnCalculateEnd( oSettings );
-     
+
     if ( bRedraw )
     {
         oSettings.oApi._fnDraw( oSettings );

diff --git a/api/fnFakeRowspan.js b/api/fnFakeRowspan.js
@@ -1,36 +1,33 @@
 /**
  * Creates rowspan cells in a column when there are two or more cells in a 
  * row with the same content, effectively grouping them together visually. 
- * <b>Note</b> - this plug-in currently only operates correctly with 
- * <b>server-side processing</b>.
+ * *Note* - this plug-in currently only operates correctly with 
+ * *server-side processing*.
+ *
  *  @name fnFakeRowspan
- *  @anchor fnFakeRowspan
+ *  @summary 
  *  @author Fredrik Wendel
  *
  *  @example
  *    $('#example').dataTable().fnFakeRowspan(3);
  */
 
-$.fn.dataTableExt.oApi.fnFakeRowspan = function ( oSettings, iColumn, bCaseSensitive ) {
+jQuery.fn.dataTableExt.oApi.fnFakeRowspan = function ( oSettings, iColumn, bCaseSensitive ) {
 	/* Fail silently on missing/errorenous parameter data. */
 	if (isNaN(iColumn)) {
 		return false;
 	}
-	 
+
 	if (iColumn < 0 || iColumn > oSettings.aoColumns.length-1) {
 		alert ('Invalid column number choosen, must be between 0 and ' + (oSettings.aoColumns.length-1));
 		return false;
 	}
-
-	var oSettings = oSettings,
-		iColumn = iColumn,
-		bCaseSensitive = (typeof(bCaseSensitive) != 'boolean' ? true : bCaseSensitive);
-
-	oSettings.aoDrawCallback.push({ "fn": fakeRowspan, "sName": "fnFakeRowspan" });
-
+
+	bCaseSensitive = (typeof(bCaseSensitive) != 'boolean' ? true : bCaseSensitive);
+
 	function fakeRowspan () {
 		var firstOccurance = null,
-			value = null, 
+			value = null,
 			rowspan = 0;
 		jQuery.each(oSettings.aoData, function (i, oData) {
 			var val = oData._aData[iColumn],
@@ -45,17 +42,19 @@ $.fn.dataTableExt.oApi.fnFakeRowspan = function ( oSettings, iColumn, bCaseSensi
 				firstOccurance = cell;
 				rowspan = 0;
 			}
-			 
+
 			if (val == value) {
 				rowspan++;
 			}
-			 
+
 			if (firstOccurance !== null && val == value && rowspan > 1) {
 				oData.nTr.removeChild(cell);
 				firstOccurance.rowSpan = rowspan;
 			}
 		});
 	}
-
+
+	oSettings.aoDrawCallback.push({ "fn": fakeRowspan, "sName": "fnFakeRowspan" });
+
 	return this;
 };
diff --git a/api/fnFilterAll.js b/api/fnFilterAll.js
@@ -2,9 +2,10 @@
  * Apply the same filter to all DataTable instances on a particular page. The
  * function call exactly matches that used by fnFilter() so regular expression
  * and individual column sorting can be used.
+ *
  *  @name fnFilterAll
- *  @anchor fnFilterAll
- *  @author <a href="http://www.kmmtiming.se/">Kristoffer Karlström</a>
+ *  @summary 
+ *  @author [Kristoffer Karlström](http://www.kmmtiming.se/)
  *
  *  @example
  *    $(document).ready(function() {
@@ -17,9 +18,9 @@
  *    });
  */
 
-$.fn.dataTableExt.oApi.fnFilterAll = function(oSettings, sInput, iColumn, bRegex, bSmart) {
+jQuery.fn.dataTableExt.oApi.fnFilterAll = function(oSettings, sInput, iColumn, bRegex, bSmart) {
     var settings = $.fn.dataTableSettings;
-    
+
     for ( var i=0 ; i<settings.length ; i++ ) {
       settings[i].oInstance.fnFilter( sInput, iColumn, bRegex, bSmart);
     }

diff --git a/api/fnFilterClear.js b/api/fnFilterClear.js
@@ -1,9 +1,10 @@
 /**
  * Remove all filtering that has been applied to a DataTable, be it column
  * based filtering or global filtering.
+ *
  *  @name fnFilterClear
- *  @anchor fnFilterClear
- *  @author <a href="http://sprymedia.co.uk">Allan Jardine</a>
+ *  @summary 
+ *  @author [Allan Jardine](http://sprymedia.co.uk)
  *
  *  @example
  *    $(document).ready(function() {
@@ -18,29 +19,31 @@
  *    } );
  */
 
-$.fn.dataTableExt.oApi.fnFilterClear  = function ( oSettings )
+jQuery.fn.dataTableExt.oApi.fnFilterClear  = function ( oSettings )
 {
+	var i, iLen;
+
 	/* Remove global filter */
 	oSettings.oPreviousSearch.sSearch = "";
-	 
+
 	/* Remove the text of the global filter in the input boxes */
 	if ( typeof oSettings.aanFeatures.f != 'undefined' )
 	{
 		var n = oSettings.aanFeatures.f;
-		for ( var i=0, iLen=n.length ; i<iLen ; i++ )
+		for ( i=0, iLen=n.length ; i<iLen ; i++ )
 		{
 			$('input', n[i]).val( '' );
 		}
 	}
-	 
+
 	/* Remove the search text for the column filters - NOTE - if you have input boxes for these
 	 * filters, these will need to be reset
 	 */
-	for ( var i=0, iLen=oSettings.aoPreSearchCols.length ; i<iLen ; i++ )
+	for ( i=0, iLen=oSettings.aoPreSearchCols.length ; i<iLen ; i++ )
 	{
 		oSettings.aoPreSearchCols[i].sSearch = "";
 	}
-	 
+
 	/* Redraw */
 	oSettings.oApi._fnReDraw( oSettings );
 };
diff --git a/api/fnFilterOnReturn.js b/api/fnFilterOnReturn.js
@@ -2,9 +2,10 @@
  * This plug-in removed the default behaviour of DataTables to filter on each
  * keypress, and replaces with it the requirement to press the enter key to
  * perform the filter.
+ *
  *  @name fnFilterOnReturn
- *  @anchor fnFilterOnReturn
- *  @author <a href="http://www.mvccms.com/">Jon Ranes</a>
+ *  @summary 
+ *  @author [Jon Ranes](http://www.mvccms.com/)
  *
  *  @example
  *    $(document).ready(function() {
@@ -14,7 +15,7 @@
 
 jQuery.fn.dataTableExt.oApi.fnFilterOnReturn = function (oSettings) {
 	var _that = this;
- 
+
 	this.each(function (i) {
 		$.fn.dataTableExt.iApiIndex = i;
 		var $this = this;