MINOR Documentation (from r104404)

git-svn-id: svn://svn.silverstripe.com/silverstripe/open/modules/sapphire/trunk@112345 467b73ca-7a2a-4603-9d3b-597d59a354a9

forms/CheckboxSetField.php

@@ -2,8 +2,27 @@
 /**
  * Displays a set of checkboxes as a logical group.
  *
- * ASSUMPTION -> IF you pass your source as an array, you pass values as an array too.
- * 				Likewise objects are handled the same.
+ * ASSUMPTION -> IF you pass your source as an array, you pass values as an array too. Likewise objects are handled the same.
+ * 
+ * Example:
+ * <code php>
+ * new CheckboxSetField(
+ *    $name = "topics",
+ *    $title = "I am interested in the following topics",
+ *    $source = array(
+ *       "1" => "Technology",
+ *       "2" => "Gardening",
+ *       "3" => "Cooking",
+ *       "4" => "Sports"
+ *    ),
+ *    $value = "1"
+ * )
+ * </code>
+ * 
+ * <b>Saving</b>
+ * The checkbox set field will save its data in one of ways:
+ *   * If the field name matches a many-many join on the object being edited, that many-many join will be updated to link to the objects selected on the checkboxes.  In this case, the keys of your value map should be the IDs of the database records.
+ *   * If the field name matches a database field, a comma-separated list of values will be saved to that field.  The keys can be text or numbers.
  * 
  * @todo Document the different source data that can be used
  * with this form field - e.g ComponentSet, DataObjectSet,

forms/FormField.php

@@ -1,9 +1,19 @@
 <?php
 /**
- * Represents a field in a form.  
+ * Represents a field in a form. 
+ *  
  * A FieldSet contains a number of FormField objects which make up the whole of a form.
  * In addition to single fields, FormField objects can be "composite", for example, the {@link TabSet}
  * field.  Composite fields let us define complex forms without having to resort to custom HTML.
+ * 
+ * <b>Subclassing</b>
+ * 
+ * Define a {@link dataValue()} method that returns a value suitable for inserting into a single database field. 
+ * For example, you might tidy up the format of a date or currency field.
+ * Define {@link saveInto()} to totally customise saving. 
+ * For example, data might be saved to the filesystem instead of the data record, 
+ * or saved to a component of the data record instead of the data record itself.
+ * 
  * @package forms
  * @subpackage core
  */