VSCode Version: 1.19
Reproduces without extensions: Yes

There is ambiguity in the language used for the onDidOpenTextDocument API. As an extension developer, I expect the event to fire when "document is opened and displayed to the user (in a document group) for the first time". To my confusion, @jrieken explained in #22561 that the event also fires when resources are opened (e.g.: from extensions):

There is a subtle difference between seeing a tab for a document and the document being open. Generally, when selecting a different tab we will (a) re-use the editor, (b) set the new document, and (c) close the former document.

Can we please update the workspace API docs to explain the lifecycle?

It'd also be good to clarify the event timing mentioned above -- when will the document from onDidOpenTextEditor(document) be assigned to one of the documents in vscode.window.visibleTextEditors?