Improvements to Extension API documentation

[lannonbr]

The current state of the documentation is at a point which it seems to display what you can use in the vscode namespace, but not to a great extent.

For instance, I'm writing an extension which runs the 'vscode.executeDefinitionProvider' command and I pass in the valid editor uri and position, and if I run the actual "Go To Definition" in the editor it works, but it is failing to do so when I use the API command.

When looking at the documentation for vscode.executeDefinitionProvider, all that is provided is what the parameters are and what it returns. Personally this is good for starting out, but when you run into loopholes where the editor does a certain function but the extension API differs even though it shouldn't, it leaves a lacking situation for how to figure out what the issue is.

With this, I think it would be a great effort to push more on not just having the docs that explain the definitions of each function, but as well common gotchas and examples on how to use the Extension API

[lannonbr]

It seems this is being handled in #1949 so I will close this issue.