--- element_example.original.module	2010-08-27 16:04:51.000000000 +0200
+++ element_example.module	2010-08-27 23:44:11.000000000 +0200
@@ -42,11 +42,18 @@ function element_example_menu() {
 
 /**
  * Implementation of hook_elements().
+ * 
+ * This defines a new form element type (vs core ones like input, text etc.)
  */
 function element_example_elements() {
+	// This is the name of the new type we're defining.
   $type['phonenumber'] = array(
+  	// Defines the type of new field. 
+  	// #input means that input is possible.
     '#input' => TRUE,
+  	// #process is an array of callback functions executed when this element is processed
     '#process' => array('element_example_phonenumber_expand'),
+  	// function executed to validate the values of this element
     '#element_validate' => array('element_example_phonenumber_validate'),
     '#default_value' => array('areacode' => '', 'number' => '', 'extension' => ''),
   );
@@ -57,12 +64,18 @@ function element_example_elements() {
  * Our process callback to expand the control.
  */
 function element_example_phonenumber_expand($element) {
+	// #tree = TRUE means that this new element is structured as a tree (a root and multiple sub-levels children.)
+	// In this case 'areacode', 'number' and 'extension' are children of the newly defined element.
+	// See @link http://drupal.org/node/48643 in the handbook for more explanations.
   $element['#tree'] = TRUE;
 
+  // This test isn't really useful here because in the actual demo form #default_values is set.
+  // But it's useful to show how to put some values in case of if they were empty.
   if (!isset($element['#value'])) {
     $element['#value'] = array('areacode' => '', 'number' => '', 'extension' => '');
   }
 
+  // Normal fields definitions.
   $element['areacode'] = array(
     '#type' => 'textfield',
     '#size' => 3,
@@ -92,9 +105,10 @@ function element_example_phonenumber_exp
 /**
  * Our element's validation function.
  *
- * We check that:
+ * Using regular expressions, we check that:
  *  - the area code is a three digit number
  *  - the number is numeric, with an optional dash
+ *	- the extension (optional) is numeric
  *
  * Any problems are attached to the form element using form_error().
  */
@@ -109,6 +123,11 @@ function element_example_phonenumber_val
       form_error($form['number'], t('The number is invalid.'));
     }
   }
+  if (isset($form['#value']['extension'])) {
+    if (0 == preg_match('/^\d*$/', $form['#value']['extension'])) {
+      form_error($form['extension'], t('The extension is invalid.'));
+    }
+  }
   return $form;
 
 }
@@ -133,6 +152,8 @@ function element_example_theme() {
  * are placed next to each other, rather than on separate lines.
  */
 function theme_phonenumber($element) {
+	// #children represents all the sublevels elements already rendered in HTML.
+	// Here it contains the three parts of the 'phonenumber' element type ('areacode', 'number' and 'extension').
   return theme('form_element', $element, '<div class="container-inline">' . $element['#children'] . '</div>');
 }
 
@@ -147,7 +168,7 @@ function element_example_demo_form() {
     '#default_value' => variable_get('element_example_test_1',
       array('areacode' => '123', 'number' => '456-7890', 'extension' => '')
     ),
-    '#description' => t('A phone number.'),
+    '#description' => t('A phone number : areacode (XXX), number (XXXXXXX or XXX-XXXX) and extension (anything in this example).'),
   );
 
   $form['element_example_test_2'] = array(
@@ -159,5 +180,6 @@ function element_example_demo_form() {
     '#description' => t('Another phone number, a fax perhaps?'),
   );
 
+  // system_settings_form($form) renders a form with the default buttons : 'Save configuration' and 'Reset to defaults'.
   return system_settings_form($form);
 }