Completions toArray() retruns docblock prose for user

[talbergs]

[dantleech]

Cool - but I guess we could develop this some more.

Should the contextual information be part of the suggestions?

When completing a parameter, there may not be any suggestions, but the contextual information for the member access expression would still be valuable.

So it may make sense to separate context from suggestions (as with issues currently)

Should we decompose the information?

As you suggested on Slack, we could break down the info into several fields and allow the consumer to do what they like with this.

This introduces a big burden on the consumer (e.g. the vim plugin, emacs plugin, deoplete, ncm-phpactor etc) as formatting from all of this info (and theres much of it) is not trivial. So I would rather keep the current synopsis - maybe think about making it configurable <with> <tokens>.

[talbergs]

I guess we could develop this some more.

Definitely, this PR only scratches a surface of a much bigger underlying idea, I see how we are already on the same page on this..

This PR lacks:

• class description is not returned
• local variable docblock description most likely is not returned
• docblock description/prose in such format * @var int $count <description-sentence> is not returned (maybe even should't)
• finer detail about completion candidate

This introduces a big burden on the consumer (e.g. the vim plugin, [ .. ]

We could surely remain formatted "info" (synopsis) and accept configuration to optionally return a lot of detail about completion candidate. This way one may even narrow down completion list to show only methods by pressing some mapping (just got got this idea).
As currently my vim completion source is a python3 plugin, it's not too hard to format things at client side.

When completing a parameter, [ .. ]

IDK how that works yet.. so be it "context" and along side with "issues" and "completions", and the finer detail on completion candidate I see fit within list of "completions". I'll try to scaffold an example JSON here:

{
  // ...
  "completions": [
    {
      "name": "getUser",
      "kind": "method",
      "info": "pub getUser(int $id): User",
      "components": [
        {
           "type": "prose",
           "value": "queries database, \n caches result, then return from cache"
        },
        {
           "type": "visibility",
           "value": "protected",
        },
        {
           "type": "returns",
           "value": "User",
        },
        // and what else not ...
      ]
    },
    {
      "name": "user",
      "kind": "property",
      "info": "public $user",
      "components": [
         // ..
      ]
  ]
}

Now it is needed to determine what and how to do next, will the "components" key be named "components" or "extra", what will be the yaml file config key (as this "components" feature increases traffic a lot, config key might default to false,