New naming and commenting conventions

Finite_State_Machine.php

@@ -2,11 +2,15 @@
 /**
  * Finite state machine skeleton
  *
- * (c) 2006 Ouest Systèmes Informatiques (OSI)
- * Licensed under the CeCILL 2.0 license
- *
- * $Id: Finite_State_Machine.php,v 1.6 2007-05-08 21:47:28 marand Exp $
+ * @copyright  (c) 2007 OSI
+ * @author     Frédéric G. MARAND
+ * @license    Licensed under the CeCILL 2.0
+ * @version    CVS: $Id: Finite_State_Machine.php,v 1.7 2007-06-03 21:24:29 marand Exp $
+ * @link       http://drupal.org/project/offload
+ * @since      Not applicable yet
+ * @package    fsm
  */
+
 require_once('misc.php'); // for func_name()
 error_reporting(E_ALL|E_STRICT);
 
@@ -132,6 +136,7 @@ abstract class Finite_State_Machine
 
   /**
    * getter for f_state
+   * @return string
    */
   public function get_state()
     {
@@ -226,11 +231,11 @@ abstract class Finite_State_Machine
    *
    * @param string $event_name
    * @param array $params the
-   * @return string resulting state
+   * @return fsm_result resulting state
    */
   public function apply_event($event_name)
     {
-    //echo func_name() . "\n";
+    // echo "Start of " . func_name() . "\n";
 
     do {
       $result = $this->apply_simple_event($event_name);
@@ -243,7 +248,7 @@ abstract class Finite_State_Machine
         $event_name = NULL;
         }
       } while($event_name);
-
+    // echo "End of " . func_name() . "\n";
     return $result;
     }
 
@@ -256,20 +261,24 @@ abstract class Finite_State_Machine
    */
   private function apply_simple_event($event_name)
     {
-    // echo func_name() . ", event = $event_name";
+    // echo "Start of " . func_name() . ", event = $event_name\n";
     $current_state = $this->f_state;
     if (($event_name == Finite_State_Machine::IDLE_EVENT) && !$this->idle_work)
       {
       return new fsm_result();
       }
 
-    if (! $this->is_event_allowed($event_name))
-      throw new Exception(func_name()
+    if (!$this->is_event_allowed($event_name))
+      {
+      die("Event $event_name not allowed in current state $current_state.\n");
+      /* throw new Exception(func_name()
         . ":  Event \"$event_name\" not accepted in current state \"$current_state\"");
+      */
+      }
 
     $outcomes = $this->get_accepted_outcomes($event_name);
 
-    $method_name = "f_$event_name";
+    $method_name = "event$event_name";
     if (!method_exists($this, $method_name))
       {
       die (func_name() . ": missing method "
@@ -300,7 +309,8 @@ abstract class Finite_State_Machine
     var_dump($result); */
     if (!isset($outcome))
       $outcome = 'NULL';
-    /* echo func_name()
+    /*
+    echo func_name()
       . ": $current_state: " . $event_name . '[' . $outcome . ']'
       . " -> $this->f_state / " . $result->fsm_action . PHP_EOL;
     */
@@ -339,6 +349,7 @@ abstract class Finite_State_Machine
    * set the current operating mode for the FSM
    *
    * @param int $mode fsm::EVENT_* constants
+   * @return int $mode fsm::EVENT_* constants
    */
   public function set_event_mode($mode)
     {
@@ -347,7 +358,7 @@ abstract class Finite_State_Machine
       case Finite_State_Machine::EVENT_NORMAL :
         if (count($this->f_queue) > 0)
           {
-          while ($event = array_shift($this->f_queue))
+          while (($event = array_shift($this->f_queue)) !== NULL)
             {
             $this->apply_event($event);
             }
@@ -440,12 +451,12 @@ abstract class Finite_State_Machine
           if (!isset($next['state']))
             $next['state'] = (string) $state['id'];
           if ($osd)
+            {
             echo "    Next(" . $next['result'] . ') = ' . $next['state'];
-          if ($osd)
             if (isset($next['action']))
               echo " + event " . $next['action'];
-          if ($osd)
             echo PHP_EOL;
+            }
           $t[$id][$ename][$eresult] = array(
             (string) $next['state'],
             (string) $next['action']);