Lots of PHPDoc formatting and cleanup

Lots more to go

lib/auth.php

@@ -3824,9 +3824,9 @@ function basic_auth_login_process($username) {
  *   if there is an error, the globals error and error_msg will be set to notify the caller
  *   that error and not to proceed with login.
  *
- * @param  (string) $username - The user to process
+ * @param  string $username - The user to process
  *
- * @return (array)  $user - The valid user information, or empty array if user must be created
+ * @return array  $user - The valid user information, or empty array if user must be created
  */
 function local_auth_login_process($username) {
 	$user = array();

lib/cdef.php

@@ -22,9 +22,16 @@
  +-------------------------------------------------------------------------+
 */
 
-/* get_cdef_item_name - resolves a single CDEF item into its text-based representation
-   @arg $cdef_item_id - the id of the individual cdef item
-   @returns - a text-based representation of the cdef item */
+/**
+ * Retrieves the name of a CDEF item based on its ID.
+ *
+ * This function fetches the type and value of a CDEF item from the database and returns
+ * the corresponding name or value based on the item's type.
+ *
+ * @param int $cdef_item_id The ID of the CDEF item.
+ * 
+ * @return string The name or value of the CDEF item.
+ */
 function get_cdef_item_name($cdef_item_id) {
 	global $cdef_functions, $cdef_operators;
 
@@ -49,11 +56,17 @@ function get_cdef_item_name($cdef_item_id) {
 			break;
 	}
 }
-
-/* get_cdef - resolves an entire CDEF into its text-based representation for use in the RRDtool 'graph'
-	 string. this name will be resolved recursively if necessary
-   @arg $cdef_id - the id of the cdef to resolve
-   @returns - a text-based representation of the cdef */
+/**
+ * Resolves an entire CDEF into its text-based representation for use in the RRDtool 'graph'
+ * string. this name will be resolved recursively if necessary
+ *
+ * This function fetches the CDEF items associated with the provided CDEF ID from the database,
+ * constructs the CDEF string by iterating through the items, and handles nested CDEFs recursively.
+ *
+ * @param int $cdef_id The ID of the CDEF to retrieve.
+ * 
+ * @return string The constructed CDEF string.
+ */
 function get_cdef($cdef_id) {
 	$cdef_items = db_fetch_assoc_prepared('SELECT id, type, value FROM cdef_items WHERE cdef_id = ? ORDER BY sequence', array($cdef_id));
 

lib/database.php

@@ -516,7 +516,7 @@ function db_execute($sql, $log = true, $db_conn = false) {
  * @param mixed $return_func
  * @param mixed $return_params
  *
- * @return (bool) '1' for success, false for failed
+ * @return mixed '1' for success, false for failed, or the return value of the return function
  */
 function db_execute_prepared($sql, $params = array(), $log = true, $db_conn = false, $execute_name = 'Exec', $default_value = true, $return_func = 'no_return_function', $return_params = array()) {
 	global $database_sessions, $error_logged, $database_default, $config, $database_hostname, $database_port, $database_total_queries, $database_last_error, $database_log, $affected_rows, $database_details;
@@ -722,7 +722,7 @@ function db_execute_prepared($sql, $params = array(), $log = true, $db_conn = fa
  * @param mixed $log
  * @param mixed $db_conn
  *
- * @return (bool)  The output of the sql query as a single variable
+ * @return bool|string  The output of the sql query as a single variable
  */
 function db_fetch_cell($sql, $col_name = '', $log = true, $db_conn = false) {
 	global $config;
@@ -749,7 +749,7 @@ function db_fetch_cell($sql, $col_name = '', $log = true, $db_conn = false) {
  * @param mixed $log
  * @param mixed $db_conn
  *
- * @return (bool) The output of the sql query as a single variable
+ * @return bool|string The output of the sql query as a single variable
  */
 function db_fetch_cell_prepared($sql, $params = array(), $col_name = '', $log = true, $db_conn = false) {
 	global $config;
@@ -763,7 +763,7 @@ function db_fetch_cell_prepared($sql, $params = array(), $col_name = '', $log =
 
 /**
  * db_fetch_cell_return - Function to process and return data from the
- *   db_fetch_cell_prepared function
+ *   db_fetch_cell function
  *
  * @param  (string) The SQL query to run
  * @param  (string) The column to return if the query is more row or associative