Annotation for array keys

dan-iway commented 3 years ago

Thanks a lot for this plugin - it already works amazingly well!

One use case I could not get to work is adding some documentation for keys where the key is not known already/dynamic.

Example:

$students = [
   'Albert' => ['age' => 12, 'grade' => 'A+'],
   'Becky' => ['age' => 13, 'grade' => 'A-'],
];

Without any annotation the completion of course only works for the exact keys 'Albert' und 'Becky', there is no completion for $students['Francis'].

Providing the following annotation specifies that the key is actually variable:

/** @var $students = [
 *   $studentName => ['age' => 12, 'grade' => 'A+']
 * ]
 */

Now $students['Francis'] offers completion for age and grade as expected, which is already great. What I am missing is a way to document $studentName in any way. Completion for $students suggests 0-4 which is a hint that it is variable but it does not tell me that it is looking for a $studentName.

Suggestion: Instead of showing 0-4 use the actual variable name from the annotation as placeholder, such as $studentName0, $studentName1, ... $studentName4 if that is possible.

Alternatively: Parse comments on the key line and use it in the suggestion, such as:

/** @var $students = [
 *   $studentName // Student Name
 *     => ['age' => 12, 'grade' => 'A+']
 * ]
 */

klesun commented 3 years ago

Hi. Thanks for the suggestion.

First of all, for info, you can add the missing 'Francis' key to the completion this way:

 *   $any ?: 'Francis' => ['age' => 12, 'grade' => 'A+']

You can also define the list of key options through a function:

You can also reference class fields:

Does either of that solve your issue, or do you want specifically the var name completion to be implemented? I could add it to my todo list, but dunno when I'd be able to get to it, likely not soon.

dan-iway commented 3 years ago

Thanks for showing me some alternative ways, sadly they won't work very well for my use case. I specifically would need a hint on the content of the key without having to specify the actual values anywhere. Similar to how you currently list 0-4 for numeric arrays meaning "any number" I'd need a way to specify "any student name" without defining which names they are, simply as a reminder that I have to provide a student name when I am at $students['.

To maybe make the problem more apparent consider an array in the form of $data[12][8] where the meaning of the keys is $data[$groupId][$entryId]. Without any possibility of hinting that the first key is $groupId and the second is $entryId I will only get some numbers for completion, which is not of much use and I will have to resort to some other form of documentation to know of the correct order.

In any case, thanks for considering the feature!

klesun commented 3 years ago

Oh, thanks, now I understand. I just remembered that there actually was an ancient functionality for showing key comments in completion: But apparently it is somewhat broken today, only working on the comments to the right and only if there is a following key...

Thanks for pointing this out, the functionality to parse comments already exists, but it's broken, so this issue transforms into a bug report and gets high priority. Really hope I'll manage to get my ass to fix the comments this weekend.

Comments support was originally introduced in https://github.com/klesun/deep-assoc-completion/commit/83be277e97e1bc15a144c7b07599143b10545f7e (briefly described in https://github.com/klesun/deep-assoc-completion/issues/8)

klesun commented 3 years ago

Fixed in 2021.02.21.001

dan-iway commented 3 years ago

Just tried it out and works as expected. Thanks a lot, this is much appreciated!

klesun / deep-assoc-completion

Annotation for array keys #176