Ensure document state synchronization before client requests (#2017)

* Added description about the order of `signatureHelp` and `didChange`

Copy this [discussion](#2011 (comment)) to the document

* Revert the specific description about the order of didChange

* Ensure document state synchronization before client requests

* Ensure document state synchronization before client requests

* add a concrete example

* add a concrete example

---------

Co-authored-by: Dirk Bäumer <[email protected]>

Author: imbant

_specifications/lsp/3.17/textDocument/didChange.md

@@ -2,6 +2,16 @@
 
 The document change notification is sent from the client to the server to signal changes to a text document. Before a client can change a text document it must claim ownership of its content using the `textDocument/didOpen` notification. In 2.0 the shape of the params has changed to include proper version numbers.
 
+Before requesting information from the server (e.g., `textDocument/completion` or `textDocument/signatureHelp`), the client must ensure that the document's state is synchronized with the server to guarantee reliable results.
+
+The following example shows how the client should synchronize the state when the user has continuous input, assuming user input triggered `textDocument/completion`:
+
+| Document Version | User Input          | Client Behavior                                 | Request                   |
+| ---------------- | ------------------- | ----------------------------------------------- | ------------------------- |
+| 5                | document change one | sync document `v5` to the server                | `textDocument/didChange`  |
+| 5                | -                   | request from the server, based on document `v5` | `textDocument/completion` |
+| 6                | document change two | sync document `v6` to the server                | `textDocument/didChange`  |
+
 _Client Capability_:
 See general synchronization [client capabilities](#textDocument_synchronization_cc).
 

_specifications/lsp/3.18/textDocument/didChange.md

@@ -2,6 +2,16 @@
 
 The document change notification is sent from the client to the server to signal changes to a text document. Before a client can change a text document it must claim ownership of its content using the `textDocument/didOpen` notification. In 2.0 the shape of the params has changed to include proper version numbers.
 
+Before requesting information from the server (e.g., `textDocument/completion` or `textDocument/signatureHelp`), the client must ensure that the document's state is synchronized with the server to guarantee reliable results.
+
+The following example shows how the client should synchronize the state when the user has continuous input, assuming user input triggered `textDocument/completion`:
+
+| Document Version | User Input          | Client Behavior                                 | Request                   |
+| ---------------- | ------------------- | ----------------------------------------------- | ------------------------- |
+| 5                | document change one | sync document `v5` to the server                | `textDocument/didChange`  |
+| 5                | -                   | request from the server, based on document `v5` | `textDocument/completion` |
+| 6                | document change two | sync document `v6` to the server                | `textDocument/didChange`  |
+
 _Client Capability_:
 See general synchronization [client capabilities](#textDocument_synchronization_cc).