apache / apache/netbeans

[php] Support array generics in doc comments

Open
#3,524 4 comments 11 reactions 0 assignees View on GitHub
kind:feature PHP
Dominant language
Java
Stars
3.1k
Forks
935
Avg merge
2d 3h
Merged PRs (30d)
17

Description

### Description

Netbeans already supports the array notation in form of `Type[]` (e.g. `@return DateTime[]`) in return and param doc comments and respects it for autocomplete. But PHP does not support this as a return type declaration (until now). It only supports `array` as return type.

So it is more naturally to document this as `array` (e.g. `@return array`. This notation is also supported by [PHPStan](https://phpstan.org/writing-php-code/phpdoc-types#general-arrays) and [Psalm](https://psalm.dev/docs/annotating_code/type_syntax/array_types/#generic-arrays). It is more flexible as it allows to declarate the type of the array key, too:
```
array
```

Sometimes you do not have a native array, but an object which is iterable and you want to declare those types, too. PHP supports the type `iterable`. So this notations should be supported, too:
```
iterable
iterable
```

It would be great if Netbeans would add support for this notations.

### Use case/motivation

Here's an example:

```php

*/
function dateTimes(): array {
return [new DateTime('yesterday'), new DateTime('today')];
}
}

$example = new Example();
foreach ($example->dateTimes() as $instanceOfDateTime) {
$instanceOfDateTime-> // shows autocomplete list, with methods of class "DateTime"
}
```

### Related issues

_No response_

### Are you willing to submit a PR?

- [ ] Yes I am willing to submit a PR!

### Code of Conduct

- [X] I agree to follow the Apache Software Foundation's [Code of Conduct](https://www.apache.org/foundation/policies/conduct.html)

Contributor guide

Open the contributing guide

Research direction

No file or test entry point is named. Start by reproducing the PHP doc-comment autocomplete example and trace the existing Type[] handling for return and param comments. Done means array, array, iterable, and iterable provide the documented element or key/value types for autocomplete.

Written by the indexing model from the issue text.

Assessment

Tech stack
php
Domain
devtools
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.