- Modified documentation comments and basic bracing to support api.module parsing

qbf.module

@@ -1,5 +1,6 @@
 <?php
 /**
+ * @file
  * Query By Form
  *
  * This module allows node modules to add a query by form tab for their node
@@ -7,11 +8,23 @@
  *
  * @copyright 2008 Ouest Systemes Informatiques (OSInet)
  * @author Frederic G. MARAND
- * @version $Id: qbf.module,v 1.9 2008-09-02 08:25:24 marand Exp $
  * @license CeCILL 2.0
  * @package QBF
  */
 
+// $Id: qbf.module,v 1.9.2.1 2008-09-19 13:27:52 marand Exp $
+
+/**
+ * Saved error reporting level.
+ *
+ * QBF module is supposed to pass parsing at E_ALL|E_STRICT, but other modules
+ * may not be so strict, so we save the level at the start of the module and
+ * restore it at the end of the module.
+ */
+global $_qbf_er;
+
+$_qbf_er = error_reporting(E_ALL | E_STRICT);
+
 /**
  * Remove this element from the generated form
  */
@@ -34,8 +47,14 @@ define('QBF_LEVEL_REQUIRED',         3);
 
 /**
  * The main QBF path
+ * @ingroup paths
  */
-define('QBF_PATH_MAIN',             'qbf');
+define('QBF_PATH_MAIN',              'qbf');
+/**
+ * The QBF autocomplete path for search fields
+ * @ingroup paths
+ */
+define('QBF_PATH_AC',                'qbf/ac');
 
 /**
  * Authorize use of QBF searches
@@ -60,11 +79,11 @@ define('QBF_TABLE_NAME',             'qbf_queries');
  * Any additional parameter passed to the function is transmitted to the form
  * generating function.
  *
+ * @ingroup forms
  * @param string $form_id
  * @return array
  */
-function qbf_transform_form($form_id)
-  {
+function qbf_transform_form($form_id) {
   $arArgs = func_get_args();
 //dsm(array('qtf' => $arArgs));
   // Fetch the basic form and rename it, passing it the caller's arguments
@@ -98,7 +117,7 @@ function qbf_transform_form($form_id)
   $newForm['#submit'] = array('qbf_submit' => array());
 // dsm($newForm);
   return $newForm;
-  }
+}
 
 /**
  * Transform a form element for QBF.
@@ -107,14 +126,14 @@ function qbf_transform_form($form_id)
  * - #qbf : array of properties
  * - #level: only within #qbf
  *
- * @see QBF_* constants
+ * See QBF_* constants
  *
+ * @ingroup forms
  * @param string $key
  * @param array $element
  * @return void
  */
-function _qbf_transform_element($key, $element)
-  {
+function _qbf_transform_element($key, $element) {
   // dsm(array('key' => $key, 'element' => $element));
 
   /**
@@ -221,7 +240,7 @@ function _qbf_transform_element($key, $element)
           {
           foreach ($element[$propertyName] as $overrideName => $overrideValue)
             {
-          	$ret[$overrideName] = $overrideValue;
+            $ret[$overrideName] = $overrideValue;
             }
           }
         }
@@ -244,56 +263,55 @@ function _qbf_transform_element($key, $element)
 
   //dsm(array('key' => $key, 'transformed element' => $ret));
   return $ret;
-  }
+}
 
 /**
  * Implement hook_perm().
  *
  * @return array
  */
-function qbf_perm()
-  {
+function qbf_perm() {
   $ret = array
     (
     QBF_PERM_QUERY,
     );
 
   return $ret;
-  }
+}
 
 /**
  * Implement hook_forms().
  *
+ * @ingroup forms
  * @return array
  */
-function qbf_forms()
-  {
+function qbf_forms() {
   $hookName = 'qbf_register';
 
   foreach (module_implements($hookName) as $module)
     {
     foreach (module_invoke($module, $hookName) as $formName)
       {
-    	$forms["qbf_$formName"] = array
-    	  (
-    	  'callback'       => 'qbf_transform_form',
-    	  'callback arguments' => array($formName),
-    	  );
+      $forms["qbf_$formName"] = array
+        (
+        'callback'       => 'qbf_transform_form',
+        'callback arguments' => array($formName),
+        );
       }
     }
 
   return $forms;
-  }
+}
 
 /**
  * Insert the query results at the bottom of the query form.
  *
+ * @ingroup forms
  * @param array $form
  * @param array $form_values
  * @return array
  */
-function qbf_after_build($form, $form_values)
-  {
+function qbf_after_build($form, $form_values) {
   if (empty($form['#post']))
     {
     return $form;
@@ -322,7 +340,7 @@ function qbf_after_build($form, $form_values)
     '#weight'  => 10,
     );
   return $form;
-  }
+}
 
 /**
  * Recursively build a query array from the form and its values
@@ -330,11 +348,11 @@ function qbf_after_build($form, $form_values)
  * In the current version, element names are supposed to be unique, even at
  * different levels in the tree.
  *
+ * @ingroup forms
  * @param array $form
  * @param array $form_values
  */
-function _qbf_extract_query($form, $form_values)
-  {
+function _qbf_extract_query($form, $form_values) {
   $name = $form['#parents'][0];
   // Elements which are removed or display-only have no place in the query
   if (array_key_exists('#qbf', $form) && array_key_exists('#level', $form['#qbf'])
@@ -350,11 +368,11 @@ function _qbf_extract_query($form, $form_values)
   // QBF level is not inherited, so this loop is outside the "if" above
   foreach (element_children($form) as $childName)
     {
-  	$ret += _qbf_extract_query($form[$childName], $form_values);
+    $ret += _qbf_extract_query($form[$childName], $form_values);
     }
 
   return $ret;
-  }
+}
 
 /**
  * Provide an optional automatic mapping mechanism for query building.
@@ -367,8 +385,7 @@ function _qbf_extract_query($form, $form_values)
  * @param array $arDefaults
  * @return array
  */
-function qbf_query_mapper($arQueryMap = array(), $arDefaults = array())
-  {
+function qbf_query_mapper($arQueryMap = array(), $arDefaults = array()) {
   $ret = array();
 
   foreach ($arQueryMap as $name => $value)
@@ -377,22 +394,22 @@ function qbf_query_mapper($arQueryMap = array(), $arDefaults = array())
       {
       $value = array();
       }
-  	$item = $value;
-
-  	foreach ($arDefaults as $defaultKey => $defaultValue)
-  	  {
-  	  if (!array_key_exists($defaultKey, $item))
-  	    {
-  	    $item[$defaultKey] = is_null($defaultValue)
-  	      ? $name
-  	      : $defaultValue;
-  	    }
-  	  // else if is already in $item, so we don't touch it
-  	  }
-  	$ret[$name] = $item;
+    $item = $value;
+
+    foreach ($arDefaults as $defaultKey => $defaultValue)
+      {
+      if (!array_key_exists($defaultKey, $item))
+        {
+        $item[$defaultKey] = is_null($defaultValue)
+          ? $name
+          : $defaultValue;
+        }
+      // else if is already in $item, so we don't touch it
+      }
+    $ret[$name] = $item;
     }
   return $ret;
-  }
+}
 
 /**
  * Load a form_values array into a form used by QBF.
@@ -402,22 +419,22 @@ function qbf_query_mapper($arQueryMap = array(), $arDefaults = array())
  *
  * @see qbf_load()
  *
+ * @ingroup forms
  * @param array $form
  * @param array $form_values
  * @return array The modified form
  */
-function qbf_import_values($element, $form_values)
-  {
+function qbf_import_values($element, $form_values) {
   foreach (element_children($element) as $childName)
     {
-  	if (!empty($form_values[$childName]))
-  	  {
-  	  $element[$childName]['#qbf']['#default_value'] = $form_values[$childName];
-  	  }
-  	$element[$childName] = qbf_import_values($element[$childName], $form_values);
+    if (!empty($form_values[$childName]))
+      {
+      $element[$childName]['#qbf']['#default_value'] = $form_values[$childName];
+      }
+    $element[$childName] = qbf_import_values($element[$childName], $form_values);
     }
   return $element;
-  }
+}
 
 /**
  * Load a saved QBF query.
@@ -427,8 +444,7 @@ function qbf_import_values($element, $form_values)
  * @param int $qid
  * @return array A form_values array usable by qbf_import_values
  */
-function qbf_load($qid)
-  {
+function qbf_load($qid) {
   $sq = 'SELECT qq.qid, qq.uid, qq.query '
       . 'FROM {%s} qq '
       . 'WHERE qq.qid = %d ';
@@ -444,10 +460,17 @@ function qbf_load($qid)
     $ret->query = unserialize($ret->query);
     }
   return $ret;
-  }
+}
 
-function qbf_submit($form_id, $form_values)
-  {
+/**
+ * Submit handler for query save form.
+ *
+ * @ingroup forms
+ * @param $form_id string
+ * @param $form_values array
+ * @return string
+ */
+function qbf_submit($form_id, $form_values) {
   switch ($form_values['op'])
     {
     case t('Search'):
@@ -463,7 +486,7 @@ function qbf_submit($form_id, $form_values)
     }
   //dsm(array('QS' => $form_values));
   return $ret;
-  }
+}
 
 /**
  * List queries owned by a given user.
@@ -471,8 +494,7 @@ function qbf_submit($form_id, $form_values)
  * @param int $uid > 0
  * @return array
  */
-function qbf_get_queries_by_user($uid)
-  {
+function qbf_get_queries_by_user($uid) {
   $sq = 'SELECT qq.qid, qq.uid, qq.name, qq.query '
       . 'FROM {%s} qq '
       . 'WHERE qq.uid = %d '
@@ -484,18 +506,17 @@ function qbf_get_queries_by_user($uid)
     $ret[$o->qid] = $o; // qid is the PK, so it is present and unique
     }
   return $ret;
-  }
+}
 
 /**
  * Save a query and return its qid.
  *
- * @global $user
- * @param string $form_id
- * @param array $form_values
+ * @ingroup forms
+ * @param $form_id string
+ * @param $form_values array
  * @return int
  */
-function _qbf_save($form_id, $form_values)
-  {
+function _qbf_save($form_id, $form_values) {
   global $user;
 
   if ($user->uid == 0)
@@ -508,10 +529,12 @@ function _qbf_save($form_id, $form_values)
   else
     {
     $sq = 'INSERT INTO {%s} (qid, uid, name, query) '
-        . "VALUES           (%d,  %d,  '%s', '%s' ) ";
+         ."VALUES           (%d,  %d,  '%s', '%s' ) ";
     $ret = db_next_id('qbf_qid');
     $q = db_query($sq, QBF_TABLE_NAME, $ret, $user->uid, $form_values['save-name'], serialize($form_values));
     }
 
   return $ret;
-  }
+}
+
+error_reporting($_qbf_er);