Update docs to indicate lists not mutable as per 7673

model/Filterable.php

@@ -2,7 +2,10 @@
 
 /**
  * Additional interface for {@link SS_List} classes that are filterable.
- * 
+ *
+ * All methods in this interface are immutable - they should return new instances with the filter
+ * applied, rather than applying the filter in place
+ *
  * @see SS_List, SS_Sortable, SS_Limitable
  */
 interface SS_Filterable {
@@ -18,22 +21,22 @@ public function canFilterBy($by);
 	/**
 	 * Filter the list to include items with these charactaristics
 	 * 
-	 * @example $list->filter('Name', 'bob'); // only bob in the list
-	 * @example $list->filter('Name', array('aziz', 'bob'); // aziz and bob in list
-	 * @example $list->filter(array('Name'=>'bob, 'Age'=>21)); // bob with the age 21
-	 * @example $list->filter(array('Name'=>'bob, 'Age'=>array(21, 43))); // bob with the Age 21 or 43
-	 * @example $list->filter(array('Name'=>array('aziz','bob'), 'Age'=>array(21, 43))); // aziz with the age 21 or 43 and bob with the Age 21 or 43
+	 * @example $list = $list->filter('Name', 'bob'); // only bob in the list
+	 * @example $list = $list->filter('Name', array('aziz', 'bob'); // aziz and bob in list
+	 * @example $list = $list->filter(array('Name'=>'bob, 'Age'=>21)); // bob with the age 21
+	 * @example $list = $list->filter(array('Name'=>'bob, 'Age'=>array(21, 43))); // bob with the Age 21 or 43
+	 * @example $list = $list->filter(array('Name'=>array('aziz','bob'), 'Age'=>array(21, 43))); // aziz with the age 21 or 43 and bob with the Age 21 or 43
 	 */
 	public function filter();
 
 	/**
 	 * Exclude the list to not contain items with these charactaristics
 	 *
-	 * @example $list->exclude('Name', 'bob'); // exclude bob from list
-	 * @example $list->exclude('Name', array('aziz', 'bob'); // exclude aziz and bob from list
-	 * @example $list->exclude(array('Name'=>'bob, 'Age'=>21)); // exclude bob that has Age 21
-	 * @example $list->exclude(array('Name'=>'bob, 'Age'=>array(21, 43))); // exclude bob with Age 21 or 43
-	 * @example $list->exclude(array('Name'=>array('bob','phil'), 'Age'=>array(21, 43))); // bob age 21 or 43, phil age 21 or 43 would be excluded
+	 * @example $list = $list->exclude('Name', 'bob'); // exclude bob from list
+	 * @example $list = $list->exclude('Name', array('aziz', 'bob'); // exclude aziz and bob from list
+	 * @example $list = $list->exclude(array('Name'=>'bob, 'Age'=>21)); // exclude bob that has Age 21
+	 * @example $list = $list->exclude(array('Name'=>'bob, 'Age'=>array(21, 43))); // exclude bob with Age 21 or 43
+	 * @example $list = $list->exclude(array('Name'=>array('bob','phil'), 'Age'=>array(21, 43))); // bob age 21 or 43, phil age 21 or 43 would be excluded
 	 */
 	public function exclude();
 

model/Limitable.php

@@ -2,7 +2,10 @@
 
 /**
  * Additional interface for {@link SS_List} classes that are limitable - able to have a subset of the list extracted.
- * 
+ *
+ * All methods in this interface are immutable - they should return new instances with the limit
+ * applied, rather than applying the limit in place
+ *
  * @see SS_List, SS_Sortable, SS_Filterable
  */
 interface SS_Limitable {

model/Sortable.php

@@ -2,7 +2,10 @@
 
 /**
  * Additional interface for {@link SS_List} classes that are sortable.
- * 
+ *
+ * All methods in this interface are immutable - they should return new instances with the sort
+ * applied, rather than applying the sort in place
+ *
  * @see SS_List, SS_Filterable, SS_Limitable
  */
 interface SS_Sortable {
@@ -19,18 +22,18 @@ public function canSortBy($by);
 	 * Sorts this list by one or more fields. You can either pass in a single
 	 * field name and direction, or a map of field names to sort directions.
 	 *
-	 * @example $list->sort('Name'); // default ASC sorting
-	 * @example $list->sort('Name DESC'); // DESC sorting
-	 * @example $list->sort('Name', 'ASC');
-	 * @example $list->sort(array('Name'=>'ASC,'Age'=>'DESC'));
+	 * @example $list = $list->sort('Name'); // default ASC sorting
+	 * @example $list = $list->sort('Name DESC'); // DESC sorting
+	 * @example $list = $list->sort('Name', 'ASC');
+	 * @example $list = $list->sort(array('Name'=>'ASC,'Age'=>'DESC'));
 	 */
 	public function sort();
 
 
 	/**
 	 * Reverses the list based on reversing the current sort.
 	 *
-	 * @example $list->reverse();
+	 * @example $list = $list->reverse();
 	 *
 	 * @return array
 	 */