Doc-comment: Improve array @param

This uses syntax from https://phpstan.org/writing-php-code/phpdoc-types#general-arrays.

int[] means an array of ints with arbitrary keys (usually strings)
list<string> means an array of strings with sequential integer keys starting at 0
list<string>[] means an arbitrary array of string lists
list<string[]> means list of arbitrary string arrays
string[][] means two dimensional array with arbitrary keys in both dimensions
array was left in the comments for https://phpstan.org/writing-php-code/phpdoc-types#array-shapes

adminer/drivers/mysql.inc.php

@@ -505,7 +505,7 @@ if (!defined('Adminer\DRIVER')) {
 
 	/** Get database collation
 	* @param string
-	* @param array result of collations()
+	* @param list<string>[] result of collations()
 	* @return string
 	*/
 	function db_collation($db, $collations) {
@@ -535,7 +535,7 @@ if (!defined('Adminer\DRIVER')) {
 	}
 
 	/** Count tables in all databases
-	* @param array
+	* @param list<string>
 	* @return int[] [$db => $tables]
 	*/
 	function count_tables($databases) {
@@ -752,7 +752,7 @@ if (!defined('Adminer\DRIVER')) {
 	}
 
 	/** Drop databases
-	* @param array
+	* @param list<string>
 	* @return bool
 	*/
 	function drop_databases($databases) {
@@ -809,7 +809,7 @@ if (!defined('Adminer\DRIVER')) {
 	* @param string "" to create
 	* @param string new name
 	* @param array of [$orig, $process_field, $after]
-	* @param array of strings
+	* @param list<string>
 	* @param string
 	* @param string
 	* @param string
@@ -853,7 +853,7 @@ if (!defined('Adminer\DRIVER')) {
 
 	/** Run commands to alter indexes
 	* @param string escaped table name
-	* @param array of ["index type", "name", ["column definition", ...]] or ["index type", "name", "DROP"]
+	* @param array[] of ["index type", "name", ["column definition", ...]] or ["index type", "name", "DROP"]
 	* @return bool
 	*/
 	function alter_indexes($table, $alter) {
@@ -867,7 +867,7 @@ if (!defined('Adminer\DRIVER')) {
 	}
 
 	/** Run commands to truncate tables
-	* @param array
+	* @param list<string>
 	* @return bool
 	*/
 	function truncate_tables($tables) {
@@ -875,7 +875,7 @@ if (!defined('Adminer\DRIVER')) {
 	}
 
 	/** Drop views
-	* @param array
+	* @param list<string>
 	* @return bool
 	*/
 	function drop_views($views) {
@@ -883,7 +883,7 @@ if (!defined('Adminer\DRIVER')) {
 	}
 
 	/** Drop tables
-	* @param array
+	* @param list<string>
 	* @return bool
 	*/
 	function drop_tables($tables) {
@@ -891,8 +891,8 @@ if (!defined('Adminer\DRIVER')) {
 	}
 
 	/** Move tables to other schema
-	* @param array
-	* @param array
+	* @param list<string>
+	* @param list<string>
 	* @param string
 	* @return bool
 	*/
@@ -921,8 +921,8 @@ if (!defined('Adminer\DRIVER')) {
 	}
 
 	/** Copy tables to other schema
-	* @param array
-	* @param array
+	* @param list<string>
+	* @param list<string>
 	* @param string
 	* @return bool
 	*/
@@ -1073,7 +1073,7 @@ if (!defined('Adminer\DRIVER')) {
 
 	/** Get approximate number of rows
 	* @param array
-	* @param array
+	* @param list<string>
 	* @return int or null if approximate number can't be retrieved
 	*/
 	function found_rows($table_status, $where) {

adminer/drivers/sqlite.inc.php

@@ -467,11 +467,11 @@ if (isset($_GET["sqlite"])) {
 	/** Recreate table
 	* @param string original name
 	* @param string new name
-	* @param array [process_field()], empty to preserve
-	* @param array [$original => idf_escape($new_column)], empty to preserve
+	* @param list<list<string>> [process_field()], empty to preserve
+	* @param string[] [$original => idf_escape($new_column)], empty to preserve
 	* @param string [format_foreign_key()], empty to preserve
 	* @param int set auto_increment to this value, 0 to preserve
-	* @param array [[$type, $name, $columns]], empty to preserve
+	* @param array[] [[$type, $name, $columns]], empty to preserve
 	* @param string CHECK constraint to drop
 	* @param string CHECK constraint to add
 	* @return bool

adminer/include/adminer.inc.php

@@ -227,8 +227,8 @@ class Adminer {
 	}
 
 	/** Print backward keys for row
-	* @param array result of $this->backwardKeys()
-	* @param array
+	* @param array[] result of $this->backwardKeys()
+	* @param string[]
 	* @return null
 	*/
 	function backwardKeysPrint($backwardKeys, $row) {
@@ -277,8 +277,8 @@ class Adminer {
 	}
 
 	/** Get descriptions of selected data
-	* @param array all data to print
-	* @param array
+	* @param list<string[]> all data to print
+	* @param array[]
 	* @return list<string[]>
 	*/
 	function rowDescriptions($rows, $foreignKeys) {
@@ -297,7 +297,7 @@ class Adminer {
 	* @param string HTML-escaped value to print
 	* @param string link to foreign key
 	* @param array single field returned from fields()
-	* @param array original value before applying editVal() and escaping
+	* @param string original value before applying editVal() and escaping
 	* @return string
 	*/
 	function selectVal($val, $link, $field, $original) {
@@ -322,7 +322,7 @@ class Adminer {
 	}
 
 	/** Print table structure in tabular format
-	* @param array data about individual fields
+	* @param array[] data about individual fields
 	* @param array
 	* @return null
 	*/
@@ -354,7 +354,7 @@ class Adminer {
 	}
 
 	/** Print list of indexes on table in tabular format
-	* @param array data about all indexes on a table
+	* @param array[] data about all indexes on a table
 	* @return null
 	*/
 	function tableIndexesPrint($indexes) {
@@ -374,8 +374,8 @@ class Adminer {
 	}
 
 	/** Print columns box in select
-	* @param array result of selectColumnsProcess()[0]
-	* @param array selectable columns
+	* @param list<string> result of selectColumnsProcess()[0]
+	* @param string[] selectable columns
 	* @return null
 	*/
 	function selectColumnsPrint($select, $columns) {
@@ -401,9 +401,9 @@ class Adminer {
 	}
 
 	/** Print search box in select
-	* @param array result of selectSearchProcess()
-	* @param array selectable columns
-	* @param array
+	* @param list<string> result of selectSearchProcess()
+	* @param string[] selectable columns
+	* @param array[]
 	* @return null
 	*/
 	function selectSearchPrint($where, $columns, $indexes) {
@@ -437,9 +437,9 @@ class Adminer {
 	}
 
 	/** Print order box in select
-	* @param array result of selectOrderProcess()
-	* @param array selectable columns
-	* @param array
+	* @param list<string> result of selectOrderProcess()
+	* @param string[] selectable columns
+	* @param array[]
 	* @return null
 	*/
 	function selectOrderPrint($order, $columns, $indexes) {
@@ -481,7 +481,7 @@ class Adminer {
 	}
 
 	/** Print action box in select
-	* @param array
+	* @param array[]
 	* @return null
 	*/
 	function selectActionPrint($indexes) {
@@ -522,16 +522,16 @@ class Adminer {
 	}
 
 	/** Print extra text in the end of a select form
-	* @param array fields holding e-mails
-	* @param array selectable columns
+	* @param string[] fields holding e-mails
+	* @param string[] selectable columns
 	* @return null
 	*/
 	function selectEmailPrint($emailFields, $columns) {
 	}
 
 	/** Process columns box in select
-	* @param array selectable columns
-	* @param array
+	* @param string[] selectable columns
+	* @param array[]
 	* @return list<list<string>> [[select_expressions], [group_expressions]]
 	*/
 	function selectColumnsProcess($columns, $indexes) {
@@ -550,8 +550,8 @@ class Adminer {
 	}
 
 	/** Process search box in select
-	* @param array
-	* @param array
+	* @param array[]
+	* @param array[]
 	* @return list<string> expressions to join by AND
 	*/
 	function selectSearchProcess($fields, $indexes) {
@@ -604,8 +604,8 @@ class Adminer {
 	}
 
 	/** Process order box in select
-	* @param array
-	* @param array
+	* @param array[]
+	* @param array[]
 	* @return list<string> expressions to join by comma
 	*/
 	function selectOrderProcess($fields, $indexes) {
@@ -635,8 +635,8 @@ class Adminer {
 	}
 
 	/** Process extras in select form
-	* @param array AND conditions
-	* @param array
+	* @param string[] AND conditions
+	* @param array[]
 	* @return bool true if processed, false to process other parts of form
 	*/
 	function selectEmailProcess($where, $foreignKeys) {
@@ -644,10 +644,10 @@ class Adminer {
 	}
 
 	/** Build SQL query used in select
-	* @param array result of selectColumnsProcess()[0]
-	* @param array result of selectSearchProcess()
-	* @param array result of selectColumnsProcess()[1]
-	* @param array result of selectOrderProcess()
+	* @param list<string> result of selectColumnsProcess()[0]
+	* @param list<string> result of selectSearchProcess()
+	* @param list<string> result of selectColumnsProcess()[1]
+	* @param list<string> result of selectOrderProcess()
 	* @param int result of selectLimitProcess()
 	* @param int index of page starting at zero
 	* @return string empty string to use default query
@@ -689,7 +689,7 @@ class Adminer {
 
 	/** Print before edit form
 	* @param string
-	* @param array
+	* @param array[]
 	* @param mixed
 	* @param bool
 	* @return null
@@ -1051,7 +1051,7 @@ class Adminer {
 	}
 
 	/** Set up syntax highlight for code and <textarea>
-	* @param array result of table_status()
+	* @param array[] result of table_status()
 	*/
 	function syntaxHighlighting($tables) {
 		global $connection;

adminer/include/driver.inc.php

@@ -75,10 +75,10 @@ abstract class SqlDriver {
 
 	/** Select data from table
 	* @param string
-	* @param array result of $adminer->selectColumnsProcess()[0]
-	* @param array result of $adminer->selectSearchProcess()
-	* @param array result of $adminer->selectColumnsProcess()[1]
-	* @param array result of $adminer->selectOrderProcess()
+	* @param list<string> result of $adminer->selectColumnsProcess()[0]
+	* @param list<string> result of $adminer->selectSearchProcess()
+	* @param list<string> result of $adminer->selectColumnsProcess()[1]
+	* @param list<string> result of $adminer->selectOrderProcess()
 	* @param int result of $adminer->selectLimitProcess()
 	* @param int index of page starting at zero
 	* @param bool whether to print the query
@@ -118,7 +118,7 @@ abstract class SqlDriver {
 
 	/** Update data in table
 	* @param string
-	* @param array escaped columns in keys, quoted data in values
+	* @param string[] escaped columns in keys, quoted data in values
 	* @param string " WHERE ..."
 	* @param int 0 or 1
 	* @param string
@@ -135,7 +135,7 @@ abstract class SqlDriver {
 
 	/** Insert data into table
 	* @param string
-	* @param array escaped columns in keys, quoted data in values
+	* @param string[] escaped columns in keys, quoted data in values
 	* @return bool
 	*/
 	function insert($table, $set) {
@@ -155,8 +155,8 @@ abstract class SqlDriver {
 
 	/** Insert or update data in table
 	* @param string
-	* @param array
-	* @param array of arrays with escaped columns in keys and quoted data in values
+	* @param list<string[]> of arrays with escaped columns in keys and quoted data in values
+	* @param int[] column names in keys
 	* @return bool
 	*/
 	function insertUpdate($table, $rows, $primary) {

adminer/include/editing.inc.php

@@ -143,7 +143,7 @@ function textarea($name, $value, $rows = 10, $cols = 80) {
 
 /** Generate HTML <select> or <input> if $options are empty
 * @param string
-* @param array
+* @param string[]
 * @param string
 * @param string
 * @param string
@@ -178,10 +178,10 @@ function json_row($key, $val = null) {
 
 /** Print table columns for type edit
 * @param string
-* @param array
-* @param array
-* @param array returned by referencable_primary()
-* @param array extra types to prepend
+* @param list<string>[]
+* @param array[]
+* @param array[] returned by referencable_primary()
+* @param list<string> extra types to prepend
 * @return null
 */
 function edit_type($key, $field, $collations, $foreign_keys = array(), $extra_types = array()) {
@@ -317,10 +317,10 @@ function type_class($type) {
 }
 
 /** Print table interior for fields editing
-* @param array
-* @param array
+* @param array[]
+* @param list<string>[]
 * @param string TABLE or PROCEDURE
-* @param array returned by referencable_primary()
+* @param array[] returned by referencable_primary()
 * @return null
 */
 function edit_fields($fields, $collations, $type = "TABLE", $foreign_keys = array()) {
@@ -382,7 +382,7 @@ function edit_fields($fields, $collations, $type = "TABLE", $foreign_keys = arra
 }
 
 /** Move fields up and down or add field
-* @param array
+* @param array[]
 * @return bool
 */
 function process_fields(&$fields) {
@@ -423,7 +423,7 @@ function process_fields(&$fields) {
 }
 
 /** Callback used in routine()
-* @param array
+* @param list<array>
 * @return string
 */
 function normalize_enum($match) {
@@ -432,7 +432,7 @@ function normalize_enum($match) {
 
 /** Issue grant or revoke commands
 * @param string GRANT or REVOKE
-* @param array
+* @param list<string>
 * @param string
 * @param string
 * @return bool
@@ -502,7 +502,7 @@ function create_trigger($on, $row) {
 
 /** Generate SQL query for creating routine
 * @param string "PROCEDURE" or "FUNCTION"
-* @param array result of routine()
+* @param string[] result of routine()
 * @return string
 */
 function create_routine($routine, $row) {
@@ -587,7 +587,7 @@ function ini_bytes($ini) {
 }
 
 /** Create link to database documentation
-* @param array JUSH => $path
+* @param string[] JUSH => $path
 * @param string HTML code
 * @return string HTML code
 */

adminer/include/functions.inc.php

@@ -81,7 +81,7 @@ function number_type() {
 }
 
 /** Disable magic_quotes_gpc
-* @param array e.g. (&$_GET, &$_POST, &$_COOKIE)
+* @param list<array> e.g. (&$_GET, &$_POST, &$_COOKIE)
 * @param bool whether to leave values as is
 * @return null modified in place
 */
@@ -261,8 +261,8 @@ function get_rows($query, $connection2 = null, $error = "<p class='error'>") {
 }
 
 /** Find unique identifier of a row
-* @param array
-* @param array result of indexes()
+* @param string[]
+* @param array[] result of indexes()
 * @return string[] or null if there is no unique identifier
 */
 function unique_array($row, $indexes) {
@@ -293,7 +293,7 @@ function escape_key($key) {
 
 /** Create SQL condition from parsed query string
 * @param array parsed query string
-* @param array
+* @param array[]
 * @return string
 */
 function where($where, $fields = array()) {
@@ -321,7 +321,7 @@ function where($where, $fields = array()) {
 
 /** Create SQL condition from query string
 * @param string
-* @param array
+* @param array[]
 * @return string
 */
 function where_check($val, $fields = array()) {
@@ -342,9 +342,9 @@ function where_link($i, $column, $value, $operator = "=") {
 }
 
 /** Get select clause for convertible fields
-* @param array
-* @param array
-* @param array
+* @param string[]
+* @param array[]
+* @param list<string>
 * @return string
 */
 function convert_fields($columns, $fields, $select = array()) {
@@ -551,7 +551,7 @@ function queries($query) {
 
 /** Apply command to all array items
 * @param string
-* @param array
+* @param list<string>
 * @param callback
 * @return bool
 */
@@ -770,7 +770,7 @@ function dump_headers($identifier, $multi_table = false) {
 }
 
 /** Print CSV row
-* @param array
+* @param string[]
 * @return null
 */
 function dump_csv($row) {
@@ -962,9 +962,9 @@ function is_shortable($field) {
 
 /** Get query to compute number of found rows
 * @param string
-* @param array
+* @param list<string>
 * @param bool
-* @param array
+* @param list<string>
 * @return string
 */
 function count_rows($table, $where, $is_group, $group) {

adminer/include/html.inc.php

@@ -87,7 +87,7 @@ function checkbox($name, $value, $checked, $label = "", $onclick = "", $class =
 }
 
 /** Generate list of HTML options
-* @param array array of strings or arrays (creates optgroup)
+* @param string[]|string[][] array of strings or arrays (creates optgroup)
 * @param mixed
 * @param bool always use array keys for value="", otherwise only string keys are used
 * @return string
@@ -116,7 +116,7 @@ function optionlist($options, $selected = null, $use_keys = false) {
 
 /** Generate HTML <select>
 * @param string
-* @param array
+* @param string[]
 * @param string
 * @param string
 * @param string
@@ -132,7 +132,7 @@ function html_select($name, $options, $value = "", $onchange = "", $labelled_by
 
 /** Generate HTML radio list
 * @param string
-* @param array
+* @param string[]
 * @param string
 * @return string
 */
@@ -198,7 +198,7 @@ function pagination($page, $current) {
 
 /** Print hidden fields
 * @param array
-* @param array
+* @param list<string>
 * @param string
 * @return bool
 */
@@ -426,7 +426,7 @@ function on_help($command, $side = 0) {
 
 /** Print edit data form
 * @param string
-* @param array
+* @param array[]
 * @param mixed
 * @param bool
 * @return null

adminer/include/plugins.inc.php

@@ -5,7 +5,7 @@ class Plugins extends Adminer {
 	public $plugins; ///< @var protected(set) array
 
 	/** Register plugins
-	* @param array object instances or null to autoload plugins from adminer-plugins/
+	* @param list<object> object instances or null to autoload plugins from adminer-plugins/
 	*/
 	function __construct($plugins) {
 		if ($plugins === null) {

editor/include/editing.inc.php

@@ -15,7 +15,7 @@ function email_header($header) {
 * @param string
 * @param string
 * @param string
-* @param array
+* @param array[]
 * @return bool
 */
 function send_mail($email, $subject, $message, $from = "", $files = array()) {

plugins/database-hide.php

@@ -10,7 +10,7 @@ class AdminerDatabaseHide {
 	protected $disabled;
 
 	/**
-	* @param array case insensitive database names in values
+	* @param list<string> case insensitive database names in values
 	*/
 	function __construct($disabled) {
 		$this->disabled = array_map('strtolower', $disabled);

plugins/designs.php

@@ -10,7 +10,7 @@ class AdminerDesigns {
 	protected $designs;
 
 	/**
-	* @param array URL in key, name in value
+	* @param list<string> URL in key, name in value
 	*/
 	function __construct($designs) {
 		$this->designs = $designs;

plugins/login-ip.php

@@ -10,8 +10,8 @@ class AdminerLoginIp {
 	protected $ips, $forwarded_for;
 
 	/** Set allowed IP addresses
-	* @param array IP address prefixes
-	* @param array X-Forwarded-For prefixes if IP address matches, empty array means anything
+	* @param list<string> IP address prefixes
+	* @param list<string> X-Forwarded-For prefixes if IP address matches, empty array means anything
 	*/
 	function __construct($ips, $forwarded_for = array()) {
 		$this->ips = $ips;

plugins/login-servers.php

@@ -10,7 +10,7 @@ class AdminerLoginServers {
 	protected $servers;
 
 	/** Set supported servers
-	* @param array [$description => ["server" => , "driver" => "server|pgsql|sqlite|..."]]
+	* @param array[] [$description => ["server" => , "driver" => "server|pgsql|sqlite|..."]]
 	*/
 	function __construct($servers) {
 		$this->servers = $servers;

plugins/master-slave.php

@@ -10,7 +10,7 @@ class AdminerMasterSlave {
 	private $masters = array();
 
 	/**
-	* @param array [$slave => $master]
+	* @param string[] [$slave => $master]
 	*/
 	function __construct($masters) {
 		$this->masters = $masters;

plugins/table-indexes-structure.php

@@ -9,7 +9,7 @@
 class AdminerTableIndexesStructure {
 
 	/** Print table structure in tabular format
-	* @Param array data about all indexes on a table
+	* @param array[] data about all indexes on a table
 	* @return bool
 	*/
 	function tableIndexesPrint($indexes) {

plugins/table-structure.php

@@ -9,7 +9,7 @@
 class AdminerTableStructure {
 
 	/** Print table structure in tabular format
-	* @param array data about individual fields
+	* @param array[] data about individual fields
 	* @return bool
 	*/
 	function tableStructurePrint($fields, $tableStatus = null) {

plugins/wymeditor.php

@@ -11,7 +11,7 @@ class AdminerWymeditor {
 	protected $scripts, $options;
 
 	/**
-	* @param array
+	* @param list<string>
 	* @param string in format "skin: 'custom', preInit: function () { }"
 	*/
 	function __construct($scripts = array("jquery/jquery.js", "wymeditor/jquery.wymeditor.min.js"), $options = "") {