From 26aa48122f05635c96e3127092362f11f0e601cb Mon Sep 17 00:00:00 2001 From: Jakub Vrana Date: Tue, 25 Mar 2025 13:08:03 +0100 Subject: [PATCH] Doc-comments: Improve array @return --- adminer/drivers/mysql.inc.php | 40 +++++++++++++++---------------- adminer/include/adminer.inc.php | 26 ++++++++++---------- adminer/include/design.inc.php | 2 +- adminer/include/driver.inc.php | 8 +++---- adminer/include/editing.inc.php | 8 +++---- adminer/include/functions.inc.php | 20 ++++++++-------- 6 files changed, 52 insertions(+), 52 deletions(-) diff --git a/adminer/drivers/mysql.inc.php b/adminer/drivers/mysql.inc.php index 6dc278d9..9bca85a7 100644 --- a/adminer/drivers/mysql.inc.php +++ b/adminer/drivers/mysql.inc.php @@ -197,14 +197,14 @@ if (!defined('Adminer\DRIVER')) { } /** Fetch next row as associative array - * @return array + * @return string[] */ function fetch_assoc() { return mysql_fetch_assoc($this->result); } /** Fetch next row as numbered array - * @return array + * @return list */ function fetch_row() { return mysql_fetch_row($this->result); @@ -465,7 +465,7 @@ if (!defined('Adminer\DRIVER')) { /** Get cached list of databases * @param bool - * @return array + * @return list */ function get_databases($flush) { // SHOW DATABASES can take a very long time so it is cached @@ -528,7 +528,7 @@ if (!defined('Adminer\DRIVER')) { } /** Get tables list - * @return array [$name => $type] + * @return string[] [$name => $type] */ function tables_list() { return get_key_vals("SELECT TABLE_NAME, TABLE_TYPE FROM information_schema.TABLES WHERE TABLE_SCHEMA = DATABASE() ORDER BY TABLE_NAME"); @@ -536,7 +536,7 @@ if (!defined('Adminer\DRIVER')) { /** Count tables in all databases * @param array - * @return array [$db => $tables] + * @return int[] [$db => $tables] */ function count_tables($databases) { $return = array(); @@ -549,7 +549,7 @@ if (!defined('Adminer\DRIVER')) { /** Get table status * @param string * @param bool return only "Name", "Engine" and "Comment" fields - * @return array [$name => ["Name" => , "Engine" => , "Comment" => , "Oid" => , "Rows" => , "Collation" => , "Auto_increment" => , "Data_length" => , "Index_length" => , "Data_free" => ]] or only inner array with $name + * @return array[] [$name => ["Name" => , "Engine" => , "Comment" => , "Oid" => , "Rows" => , "Collation" => , "Auto_increment" => , "Data_length" => , "Index_length" => , "Data_free" => ]] or only inner array with $name */ function table_status($name = "", $fast = false) { $return = array(); @@ -596,7 +596,7 @@ if (!defined('Adminer\DRIVER')) { /** Get information about fields * @param string - * @return array [$name => ["field" =>, "full_type" =>, "type" =>, "length" =>, "unsigned" =>, "default" =>, "null" =>, "auto_increment" =>, "on_update" =>, "collation" =>, "privileges" =>, "comment" =>, "primary" =>, "generated" =>]] + * @return array[] [$name => ["field" =>, "full_type" =>, "type" =>, "length" =>, "unsigned" =>, "default" =>, "null" =>, "auto_increment" =>, "on_update" =>, "collation" =>, "privileges" =>, "comment" =>, "primary" =>, "generated" =>]] */ function fields($table) { global $connection; @@ -652,7 +652,7 @@ if (!defined('Adminer\DRIVER')) { /** Get table indexes * @param string * @param string Db to use - * @return array [$key_name => ["type" => , "columns" => [], "lengths" => [], "descs" => []]] + * @return array[] [$key_name => ["type" => , "columns" => [], "lengths" => [], "descs" => []]] */ function indexes($table, $connection2 = null) { $return = array(); @@ -668,7 +668,7 @@ if (!defined('Adminer\DRIVER')) { /** Get foreign keys in table * @param string - * @return array [$name => ["db" => , "ns" => , "table" => , "source" => [], "target" => [], "on_delete" => , "on_update" => ]] + * @return array[] [$name => ["db" => , "ns" => , "table" => , "source" => [], "target" => [], "on_delete" => , "on_update" => ]] */ function foreign_keys($table) { global $driver; @@ -707,7 +707,7 @@ if (!defined('Adminer\DRIVER')) { } /** Get sorted grouped list of collations - * @return array + * @return list[] */ function collations() { $return = array(); @@ -720,7 +720,7 @@ if (!defined('Adminer\DRIVER')) { } ksort($return); foreach ($return as $key => $val) { - asort($return[$key]); + sort($return[$key]); } return $return; } @@ -971,7 +971,7 @@ if (!defined('Adminer\DRIVER')) { /** Get defined triggers * @param string - * @return array [$name => [$timing, $event]] + * @return array[] [$name => [$timing, $event]] */ function triggers($table) { $return = array(); @@ -982,7 +982,7 @@ if (!defined('Adminer\DRIVER')) { } /** Get trigger options - * @return array ["Timing" => [], "Event" => [], "Type" => []] + * @return list[] ["Timing" => [], "Event" => [], "Type" => []] */ function trigger_options() { return array( @@ -1032,14 +1032,14 @@ if (!defined('Adminer\DRIVER')) { } /** Get list of routines - * @return array ["SPECIFIC_NAME" => , "ROUTINE_NAME" => , "ROUTINE_TYPE" => , "DTD_IDENTIFIER" => ] + * @return list ["SPECIFIC_NAME" => , "ROUTINE_NAME" => , "ROUTINE_TYPE" => , "DTD_IDENTIFIER" => ] */ function routines() { return get_rows("SELECT ROUTINE_NAME AS SPECIFIC_NAME, ROUTINE_NAME, ROUTINE_TYPE, DTD_IDENTIFIER FROM information_schema.ROUTINES WHERE ROUTINE_SCHEMA = DATABASE()"); } /** Get list of available routine languages - * @return array + * @return list */ function routine_languages() { return array(); // "SQL" not required @@ -1082,7 +1082,7 @@ if (!defined('Adminer\DRIVER')) { /* Not used is MySQL but checked in compile.php: /** Get user defined types - * @return array [$id => $name] + * @return string[] [$id => $name] function types() { return array(); } @@ -1095,7 +1095,7 @@ if (!defined('Adminer\DRIVER')) { } /** Get existing schemas - * @return array + * @return list function schemas() { return array(); } @@ -1158,21 +1158,21 @@ if (!defined('Adminer\DRIVER')) { } /** Get server variables - * @return array [[$name, $value]] + * @return list [[$name, $value]] */ function show_variables() { return get_rows("SHOW VARIABLES"); } /** Get status variables - * @return array [[$name, $value]] + * @return list [[$name, $value]] */ function show_status() { return get_rows("SHOW STATUS"); } /** Get process list - * @return array [$row] + * @return list [$row] */ function process_list() { return get_rows("SHOW FULL PROCESSLIST"); diff --git a/adminer/include/adminer.inc.php b/adminer/include/adminer.inc.php index a56e9633..98ca1439 100644 --- a/adminer/include/adminer.inc.php +++ b/adminer/include/adminer.inc.php @@ -60,14 +60,14 @@ class Adminer { /** Get cached list of databases * @param bool - * @return array + * @return list */ function databases($flush = true) { return get_databases($flush); } /** Get list of schemas - * @return array + * @return list */ function schemas() { return schemas(); @@ -87,7 +87,7 @@ class Adminer { } /** Get Content Security Policy headers - * @return array of arrays with directive name in key, allowed sources in value + * @return list of arrays with directive name in key, allowed sources in value */ function csp() { return csp(); @@ -105,7 +105,7 @@ class Adminer { } /** Get URLs of the CSS files - * @return array of strings + * @return list */ function css() { $return = array(); @@ -211,7 +211,7 @@ class Adminer { /** Get foreign keys for table * @param string - * @return array same format as foreign_keys() + * @return array[] same format as foreign_keys() */ function foreignKeys($table) { return foreign_keys($table); @@ -220,7 +220,7 @@ class Adminer { /** Find backward keys for table * @param string * @param string - * @return array $return[$target_table]["keys"][$key_name][$target_column] = $source_column; $return[$target_table]["name"] = $this->tableName($target_table); + * @return array[] $return[$target_table]["keys"][$key_name][$target_column] = $source_column; $return[$target_table]["name"] = $this->tableName($target_table); */ function backwardKeys($table, $tableName) { return array(); @@ -279,7 +279,7 @@ class Adminer { /** Get descriptions of selected data * @param array all data to print * @param array - * @return array + * @return list */ function rowDescriptions($rows, $foreignKeys) { return $rows; @@ -532,7 +532,7 @@ class Adminer { /** Process columns box in select * @param array selectable columns * @param array - * @return array [[select_expressions], [group_expressions]] + * @return list> [[select_expressions], [group_expressions]] */ function selectColumnsProcess($columns, $indexes) { global $driver; @@ -552,7 +552,7 @@ class Adminer { /** Process search box in select * @param array * @param array - * @return array expressions to join by AND + * @return list expressions to join by AND */ function selectSearchProcess($fields, $indexes) { global $connection, $driver; @@ -606,7 +606,7 @@ class Adminer { /** Process order box in select * @param array * @param array - * @return array expressions to join by comma + * @return list expressions to join by comma */ function selectOrderProcess($fields, $indexes) { $return = array(); @@ -699,7 +699,7 @@ class Adminer { /** Functions displayed in edit form * @param array single field from fields() - * @return array + * @return list */ function editFunctions($field) { global $driver; @@ -779,7 +779,7 @@ class Adminer { } /** Return export output options - * @return array + * @return string[] */ function dumpOutput() { $return = array('text' => lang('open'), 'file' => lang('save')); @@ -790,7 +790,7 @@ class Adminer { } /** Return export format options - * @return array empty to disable export + * @return string[] empty to disable export */ function dumpFormat() { return (support("dump") ? array('sql' => 'SQL') : array()) + array('csv' => 'CSV,', 'csv;' => 'CSV;', 'tsv' => 'TSV'); diff --git a/adminer/include/design.inc.php b/adminer/include/design.inc.php index dc657bcc..92a2ca31 100644 --- a/adminer/include/design.inc.php +++ b/adminer/include/design.inc.php @@ -149,7 +149,7 @@ function page_headers() { } /** Get Content Security Policy headers -* @return array of arrays with directive name in key, allowed sources in value +* @return list of arrays with directive name in key, allowed sources in value */ function csp() { return array( diff --git a/adminer/include/driver.inc.php b/adminer/include/driver.inc.php index a97224e0..014ce199 100644 --- a/adminer/include/driver.inc.php +++ b/adminer/include/driver.inc.php @@ -46,14 +46,14 @@ abstract class SqlDriver { } /** Get all types - * @return array [$type => $maximum_unsigned_length, ...] + * @return int[] [$type => $maximum_unsigned_length, ...] */ function types() { return call_user_func_array('array_merge', array_values($this->types)); } /** Get structured types - * @return array [$description => [$type, ...], ...] + * @return list[] [$description => [$type, ...], ...] */ function structuredTypes() { return array_map('array_keys', $this->types); @@ -253,7 +253,7 @@ abstract class SqlDriver { } /** Get supported engines - * @return array + * @return list */ function engines() { return array(); @@ -269,7 +269,7 @@ abstract class SqlDriver { /** Get defined check constraints * @param string - * @return array [$name => $clause] + * @return string[] [$name => $clause] */ function checkConstraints($table) { // MariaDB contains CHECK_CONSTRAINTS.TABLE_NAME, MySQL and PostrgreSQL not diff --git a/adminer/include/editing.inc.php b/adminer/include/editing.inc.php index e89a1f27..a1bf659c 100644 --- a/adminer/include/editing.inc.php +++ b/adminer/include/editing.inc.php @@ -6,9 +6,9 @@ namespace Adminer; /** Print select result * @param Result * @param Db connection to examine indexes -* @param array +* @param string[] * @param int -* @return array $orgtables +* @return string[] $orgtables */ function select($result, $connection2 = null, $orgtables = array(), $limit = 0) { $links = array(); // colno => orgtable - create links from these columns @@ -102,7 +102,7 @@ function select($result, $connection2 = null, $orgtables = array(), $limit = 0) /** Get referencable tables with single column primary key except self * @param string -* @return array [$table_name => $field] +* @return array[] [$table_name => $field] */ function referencable_primary($self) { $return = array(); // table_name => field @@ -262,7 +262,7 @@ function process_type($field, $collate = "COLLATE") { /** Create SQL string from field * @param array basic field information * @param array information about field type -* @return array ["field", "type", "NULL", "DEFAULT", "ON UPDATE", "COMMENT", "AUTO_INCREMENT"] +* @return list ["field", "type", "NULL", "DEFAULT", "ON UPDATE", "COMMENT", "AUTO_INCREMENT"] */ function process_field($field, $type_field) { // MariaDB exports CURRENT_TIMESTAMP as a function. diff --git a/adminer/include/functions.inc.php b/adminer/include/functions.inc.php index 26dd449d..ad47b8e2 100644 --- a/adminer/include/functions.inc.php +++ b/adminer/include/functions.inc.php @@ -200,7 +200,7 @@ function get_val($query, $field = 0) { /** Get list of values from database * @param string * @param mixed -* @return array +* @return list */ function get_vals($query, $column = 0) { global $connection; @@ -218,7 +218,7 @@ function get_vals($query, $column = 0) { * @param string * @param Db * @param bool -* @return array +* @return string[] */ function get_key_vals($query, $connection2 = null, $set_keys = true) { global $connection; @@ -243,7 +243,7 @@ function get_key_vals($query, $connection2 = null, $set_keys = true) { * @param string * @param Db * @param string -* @return array of associative arrays +* @return list of associative arrays */ function get_rows($query, $connection2 = null, $error = "

") { global $connection; @@ -263,7 +263,7 @@ function get_rows($query, $connection2 = null, $error = "

") { /** Find unique identifier of a row * @param array * @param array result of indexes() -* @return array or null if there is no unique identifier +* @return string[] or null if there is no unique identifier */ function unique_array($row, $indexes) { foreach ($indexes as $index) { @@ -381,7 +381,7 @@ function cookie($name, $value, $lifetime = 2592000) { /** Get settings stored in a cookie * @param string -* @return array +* @return mixed[] */ function get_settings($cookie) { parse_str($_COOKIE[$cookie], $settings); @@ -399,7 +399,7 @@ function get_setting($key, $cookie = "adminer_settings") { } /** Store settings to a cookie -* @param array +* @param mixed[] * @param string * @return bool */ @@ -701,7 +701,7 @@ function friendly_url($val) { /** Get status of a single table and fall back to name on error * @param string * @param bool -* @return array +* @return array[] */ function table_status1($table, $fast = false) { $return = table_status($table, $fast); @@ -710,7 +710,7 @@ function table_status1($table, $fast = false) { /** Find out foreign keys for each column * @param string -* @return array [$col => []] +* @return list[] [$col => []] */ function column_foreign_keys($table) { global $adminer; @@ -724,7 +724,7 @@ function column_foreign_keys($table) { } /** Compute fields() from $_POST edit data -* @return array +* @return array[] */ function fields_from_edit() { global $driver; @@ -977,7 +977,7 @@ function count_rows($table, $where, $is_group, $group) { /** Run query which can be killed by AJAX call after timing out * @param string -* @return array of strings +* @return string[] */ function slow_query($query) { global $adminer, $token, $driver;