From a191019e7a6bb7173a1c48c01ec303d65a03ae2c Mon Sep 17 00:00:00 2001
From: Ingo Schommer <ingo@silverstripe.com>
Date: Fri, 15 Oct 2010 00:04:14 +0000
Subject: [PATCH] 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 | 23 +++++++++++++++++++++--
 forms/FormField.php        | 12 +++++++++++-
 2 files changed, 32 insertions(+), 3 deletions(-)

diff --git a/forms/CheckboxSetField.php b/forms/CheckboxSetField.php
index 58f543050..62c366275 100755
--- a/forms/CheckboxSetField.php
+++ b/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,
diff --git a/forms/FormField.php b/forms/FormField.php
index 6e5b5218e..a28700db1 100755
--- a/forms/FormField.php
+++ b/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
  */