make docs, signatures more explicit about doc open lifecycle

Author: bollwyvl

CHANGELOG.md

@@ -11,6 +11,12 @@
   - ignores malformed diagnostic ranges, enabling markdown support ([#165][])
   - passes tests on Python 3.8 on Windows ([#165][])
 
+- bug fixes
+
+  - reports files are open only after installing all handlers to avoid missing messages ([#201][])
+
+[#201]: https://github.com/krassowski/jupyterlab-lsp/issues/201
+
 ### `lsp-ws-connection 0.4.0` (unreleased)
 
 - breaking changes

packages/jupyterlab-lsp/src/adapters/jupyterlab/file_editor.ts

@@ -70,6 +70,9 @@ export class FileEditorAdapter extends JupyterLabWidgetAdapter {
     this.connect_contentChanged_signal();
 
     console.log('LSP: file ready for connection:', this.path);
+
+    // connect the document, but do not open it as the adapter will handle this
+    // after registering all features
     this.connect_document(this.virtual_editor.virtual_document).catch(
       console.warn
     );

packages/jupyterlab-lsp/src/adapters/jupyterlab/jl_adapter.ts

@@ -241,7 +241,7 @@ export abstract class JupyterLabWidgetAdapter
     // recreate virtual document using current path and language
     this.virtual_editor.create_virtual_document();
     // reconnect
-    this.connect_document(this.virtual_editor.virtual_document).catch(
+    this.connect_document(this.virtual_editor.virtual_document, true).catch(
       console.warn
     );
   }
@@ -287,36 +287,62 @@ export abstract class JupyterLabWidgetAdapter
     });
   }
 
-  protected async connect_document(virtual_document: VirtualDocument) {
+  /**
+   * Opens a connection for the document. The connection may or may
+   * not be initialized, yet, and depending on when this is called, the client
+   * may not be fully connected. In
+   *
+   * @param virtual_document a VirtualDocument
+   * @param send_open whether to open the document immediately
+   */
+  protected async connect_document(
+    virtual_document: VirtualDocument,
+    send_open = false
+  ): Promise<void> {
     virtual_document.changed.connect(this.document_changed, this);
 
     virtual_document.foreign_document_opened.connect(
       this.on_foreign_document_opened,
       this
     );
-    return await this.connect(virtual_document).catch(console.warn);
+
+    const connection_context = await this.connect(virtual_document).catch(
+      console.warn
+    );
+
+    if (!send_open) {
+      return;
+    }
+
+    if (connection_context && connection_context.connection) {
+      connection_context.connection.sendOpenWhenReady(
+        virtual_document.document_info
+      );
+    } else {
+      console.warn(`Connection for ${virtual_document.path} was not opened`);
+    }
   }
 
+  /**
+   * Handler for opening a document contained in a larger document. The assumption
+   * is that the editor already exists for this this, and as such the document
+   * should be queued for immediate opening.
+   *
+   * @param host the VirtualDocument that contains the VirtualDocument in another language
+   * @param context information about the foreign VirtualDocument
+   */
   protected async on_foreign_document_opened(
     host: VirtualDocument,
     context: IForeignContext
   ) {
     const { foreign_document } = context;
 
-    const connection_context = await this.connect_document(foreign_document);
+    await this.connect_document(foreign_document, true);
 
     foreign_document.foreign_document_closed.connect(
       this.on_foreign_document_closed,
       this
     );
-
-    if (connection_context) {
-      connection_context.connection.sendOpenWhenReady(
-        foreign_document.document_info
-      );
-    } else {
-      console.warn(`Connection for ${foreign_document.path} was not be opened`);
-    }
   }
 
   on_foreign_document_closed(host: VirtualDocument, context: IForeignContext) {

packages/jupyterlab-lsp/src/adapters/jupyterlab/notebook.ts

@@ -158,6 +158,8 @@ export class NotebookAdapter extends JupyterLabWidgetAdapter {
     );
     this.connect_contentChanged_signal();
 
+    // connect the document, but do not open it as the adapter will handle this
+    // after registering all features
     this.connect_document(this.virtual_editor.virtual_document).catch(
       console.warn
     );