Improving documentation for PaginatorHelper::sort() Fixes #210

cake/libs/view/helpers/paginator.php

@@ -207,11 +207,13 @@ function next($title = 'Next >>', $options = array(), $disabledTitle = null, $di
 		return $this->__pagingLink('Next', $title, $options, $disabledTitle, $disabledOptions);
 	}
 /**
- * Generates a sorting link
+ * Generates a sorting link. Sets named parameters for the sort and direction.  Handles
+ * direction switching automatically.
  *
- * @param  string $title Title for the link.
- * @param  string $key The name of the key that the recordset should be sorted.
- * @param  array $options Options for sorting link. See #options for list of keys.
+ * @param string $title Title for the link.
+ * @param string $key The name of the key that the recordset should be sorted.  If $key is null
+ *   $title will be used for the key, and a title will be generated by inflection.
+ * @param array $options Options for sorting link. See #options for list of keys.
  * @return string A link sorting default by 'asc'. If the resultset is sorted 'asc' by the specified
  *  key the returned link will sort by 'desc'.
  */