diff --git a/cake/libs/controller/components/paginator.php b/cake/libs/controller/components/paginator.php
index c857b573e..5c0c4b940 100644
--- a/cake/libs/controller/components/paginator.php
+++ b/cake/libs/controller/components/paginator.php
@@ -267,9 +267,9 @@ class PaginatorComponent extends Component {
  * - General pagination settings
  * - Model specific settings.
  * - Request parameters
- * - $options argument.
  *
- * The result of this method is the aggregate of all the option sets combined together.
+ * The result of this method is the aggregate of all the option sets combined together.  You can change
+ * PaginatorComponent::$whitelist to modify which options/values can be set using request parameters.
  *
  * @param string $alias Model alias being paginated, if the general settings has a key with this value
  *   that key's settings will be used for pagination instead of the general ones.
@@ -294,7 +294,7 @@ class PaginatorComponent extends Component {
  * will be used.
  *
  * @param string $alias Model name to get default settings for.
- * @return array
+ * @return array An array of pagination defaults for a model, or the general settings.
  */
 	public function getDefaults($alias) {
 		if (isset($this->settings[$alias])) {
@@ -313,6 +313,9 @@ class PaginatorComponent extends Component {
  * virtualFields can be sorted on.  The direction param will also be sanitized.  Lastly
  * sort + direction keys will be converted into the model friendly order key.
  *
+ * You can use the whitelist parameter to control which columns/fields are available for sorting.
+ * This helps prevent users from ordering large result sets on un-indexed values.
+ *
  * @param Model $object The model being paginated.
  * @param array $options The pagination options being used for this request.
  * @param array $whitelist The list of columns that can be used for sorting.  If empty all keys are allowed.
diff --git a/cake/libs/view/helpers/paginator.php b/cake/libs/view/helpers/paginator.php
index aaba58297..8fe9e40ec 100644
--- a/cake/libs/view/helpers/paginator.php
+++ b/cake/libs/view/helpers/paginator.php
@@ -42,7 +42,8 @@ class PaginatorHelper extends AppHelper {
 	private $__defaultModel = null;
 
 /**
- * The class used for 'Ajax' pagination links.
+ * The class used for 'Ajax' pagination links. Defaults to JsHelper.  You should make sure
+ * that JsHelper is defined as a helper before PaginatorHelper, if you want to customize the JsHelper.
  *
  * @var string
  */
@@ -53,20 +54,20 @@ class PaginatorHelper extends AppHelper {
  *
  * The values that may be specified are:
  *
- * - `$options['format']` Format of the counter. Supported formats are 'range' and 'pages'
+ * - `format` Format of the counter. Supported formats are 'range' and 'pages'
  *    and custom (default). In the default mode the supplied string is parsed and constants are replaced
  *    by their actual values.
- *    Constants: %page%, %pages%, %current%, %count%, %start%, %end% .
- * - `$options['separator']` The separator of the actual page and number of pages (default: ' of ').
- * - `$options['url']` Url of the action. See Router::url()
- * - `$options['url']['sort']`  the key that the recordset is sorted.
- * - `$options['url']['direction']` Direction of the sorting (default: 'asc').
- * - `$options['url']['page']` Page # to display.
- * - `$options['model']` The name of the model.
- * - `$options['escape']` Defines if the title field for the link should be escaped (default: true).
- * - `$options['update']` DOM id of the element updated with the results of the AJAX call.
+ *    placeholders: %page%, %pages%, %current%, %count%, %start%, %end% .
+ * - `separator` The separator of the actual page and number of pages (default: ' of ').
+ * - `url` Url of the action. See Router::url()
+ * - `url['sort']`  the key that the recordset is sorted.
+ * - `url['direction']` Direction of the sorting (default: 'asc').
+ * - `url['page']` Page number to use in links.
+ * - `model` The name of the model.
+ * - `escape` Defines if the title field for the link should be escaped (default: true).
+ * - `update` DOM id of the element updated with the results of the AJAX call.
  *     If this key isn't specified Paginator will use plain HTML links.
- * - `$options['paging']['paramType']` The type of parameters to use when creating links.  Valid options are 
+ * - `paging['paramType']` The type of parameters to use when creating links.  Valid options are 
  *     'querystring', 'named', and 'route'.  See PaginatorComponent::$settings for more information.
  * - `convertKeys` - A list of keys in url arrays that should be converted to querysting params
  *    if paramType == 'querystring'.