Add some code documentation skeletons and comment some methods/functions.

Signed-off-by: Jérôme Benoit <jerome.benoit@piment-noir.org>

diff --git a/index.php b/index.php
index 5c12c9e0477395dd88a9d26353b096dcd9e58440..33db471dab67fc5cf393608b7f00565ffa2f8f09 100644 (file)
--- a/index.php
+++ b/index.php
@@ -13,7 +13,7 @@ if (!isset($page)) {
 }
 
 /**
- * form MUST have an hidden field named 'form' to enable proper routing
+ * form MUST have an hidden field named 'form' to enable proper routing here
  */
 $form = filter_input(INPUT_POST, 'form', FILTER_SANITIZE_URL);
 $is_form = true;
@@ -24,6 +24,10 @@ if (!isset($form)) {
 
 //var_dump($_SESSION);
 
+/**
+ * [get_action_type description]
+ * @return [type] [description]
+ */
 function get_action_type() {
     global $is_page, $is_form;
 
@@ -38,6 +42,11 @@ function get_action_type() {
     }
 }
 
+/**
+ * [get_url_action description]
+ * @param  [type] $action_type [description]
+ * @return [type]              [description]
+ */
 function get_url_action($action_type) {
     global $page, $form;
 
@@ -72,6 +81,12 @@ function validate_url_action($action_name)
     return $configs['actions'][0];
 }
 
+/**
+ * [display_action description]
+ * @param  [type] $action_name [description]
+ * @param  [type] $action_type [description]
+ * @return [type]              [description]
+ */
 function display_action($action_name, $action_type)
 {
     global $configs;

diff --git a/lib/db.php b/lib/db.php
index bcbf5aebc2709265decce8a7d53ac86099f190f5..1a870c49f118e285c2fafcaa22178f53372c482a 100644 (file)
--- a/lib/db.php
+++ b/lib/db.php
@@ -12,11 +12,13 @@ class CustomDB
     private $current_result;
 
     /**
-     * [__construct description]
-     * @param [type] $host     [description]
-     * @param [type] $username [description]
-     * @param [type] $password [description]
-     * @param [type] $dbname   [description]
+     * __construct class constructor method that permit to initialize
+     * the connection to the RDBMS database
+     * @param string $host     RDBMS hostname
+     * @param string $username RDBMS user
+     * @param string $password RDBMS user password
+     * @param string $dbname   RDBMS database to use
+     * @return object an object which represents the connection to a RDBMS Server.
      */
     public function __construct($host, $username, $password, $dbname)
     {
@@ -40,8 +42,8 @@ class CustomDB
     } */
 
     /**
-     * [close description]
-     * @return [type] [description]
+     * close method to close the opened connection to the RDBMS server
+     * @return void
      */
     public function close()
     {
@@ -53,9 +55,10 @@ class CustomDB
     }
 
     /**
-     * [query description]
-     * @param  [type] $sql_query [description]
-     * @return [type]            [description]
+     * query method that permit to execute a SQL query
+     * @param  string $sql_query the SQL query to execute
+     * @return mysqli_result object or FALSE on failure and TRUE for queries
+     * without results
      */
     public function query($sql_query)
     {
@@ -66,9 +69,9 @@ class CustomDB
     }
 
     /**
-     * [prepare_query description]
-     * @param  [type] $prepared_query [description]
-     * @return [type]                 [description]
+     * prepare_query method for parametrized SQL query preparation
+     * @param  string $prepared_query parametrized SQL query to prepare
+     * @return object statement object or FALSE if an error occurred
      */
     public function prepare_query($prepared_query)
     {
@@ -82,10 +85,10 @@ class CustomDB
     }
 
     /**
-     * [prepared_query_bind_param description]
-     * @param  [type] $types  [description]
-     * @param  [type] $params [description]
-     * @return [type]         [description]
+     * prepared_query_bind_param link parameters values to a prepared SQL query
+     * @param  string $types  parameters types
+     * @param  array $params unidimensional array of parameters values
+     * @return boolean TRUE on success or FALSE on failure
      */
     public function prepared_query_bind_param($types, $params)
     {
@@ -97,8 +100,9 @@ class CustomDB
     }
 
     /**
-     * [run_prepared_query description]
-     * @return [type] [description]
+     * run_prepared_query method that execute a parametrized SQL query linked
+     * with its parameters values
+     * @return boolean TRUE on success or FALSE on failure
      */
     public function run_prepared_query()
     {