Invalid PHPDocs - optional array keys

[AnnaNtagiou]

A lot of PHPDocs were invalid as they had comments at the EOL.

After PHPStan 2.1.6, which supports comments at EOL, the PHPDocs are valid but incorrect. There are array keys that are not required but are not defined as optional.

For example, in ClientEndpointsTrait we have this PHPDoc.

         * @param array{
	 *     id: string, // (REQUIRED) Script ID
	 *     context: string, //  Script context
	 *     timeout: time, // Explicit operation timeout
	 *     master_timeout: time, // Specify timeout for connection to master
	 *     pretty: boolean, // Pretty format the returned JSON response. (DEFAULT: false)
	 *     human: boolean, // Return human readable values for statistics. (DEFAULT: true)
	 *     error_trace: boolean, // Include the stack trace of returned errors. (DEFAULT: false)
	 *     source: string, // The URL-encoded request definition. Useful for libraries that do not accept a request body for non-POST requests.
	 *     filter_path: list, // A comma-separated list of filters used to reduce the response.
	 *     body: array, // (REQUIRED) The document
	 * } $params

While only the id and body keys are required, the rest of the keys are not optional.

[AJenbo]

To the person looking in to this, optional keys should end with a ?:

       /**
         * @param array{
	 *     id: string, // (REQUIRED) Script ID
	 *     context?: string, //  Script context
	 *     timeout?: time, // Explicit operation timeout
	 *     master_timeout?: time, // Specify timeout for connection to master
	 *     pretty?: boolean, // Pretty format the returned JSON response. (DEFAULT: false)
	 *     human?: boolean, // Return human readable values for statistics. (DEFAULT: true)
	 *     error_trace?: boolean, // Include the stack trace of returned errors. (DEFAULT: false)
	 *     source?: string, // The URL-encoded request definition. Useful for libraries that do not accept a request body for non-POST requests.
	 *     filter_path?: string, // A comma-separated list of filters used to reduce the response.
	 *     body: array, // (REQUIRED) The document
	 * } $params

Also time is not a PHP type, should it be string, DateTime or int????

[kostirez1]

This is also the case for Cluster::health()? The PHPDoc specifies index (and all others) as mandatory, even though the function body proves otherwise.

Causing PHPStan to:

         Parameter #1 $params of method                                         
         Elastic\Elasticsearch\Endpoints\Cluster::health() expects              
         array{index: list, expand_wildcards:                                   
         Elastic\Elasticsearch\Endpoints\enum, level:                           
         Elastic\Elasticsearch\Endpoints\enum, local: bool, master_timeout:     
         Elastic\Elasticsearch\Endpoints\time, timeout:                         
         Elastic\Elasticsearch\Endpoints\time, wait_for_active_shards: string,  
         wait_for_nodes: string, ...}, array{timeout: '10s'} given.             
         🪪  argument.type                                                      
         💡 Array does not have offset 'index'.       

Perhaps this should be handled throughout the entire repository right from the start? Thanks for bringing this up and putting the time in this fast!

[ezimuel]

Thanks @AJenbo, @AnnaNtagiou and @kostirez1 for your feedback. I need to update and fix some of these PHPDoc, when I implemented this was a very experimental feature.

[AnnaNtagiou]

@ezimuel I fixed the optional array keys in Indices and ClientEndpointsTrait with #1426. Could you have a look if you have time?