Merge pull request #2305 from ahoppen/bsp-request-advice

Add advice that the `workspace/buildTargets` etc. requests should return ASAP and not wait for expensive computations

Author: ahoppen

Contributor Documentation/Implementing a BSP server.md

@@ -23,6 +23,8 @@ In order to provide semantic functionality for source files, the BSP server must
 - `buildTarget/didChange`
 - `workspace/waitForBuildSystemUpdates`
 
+The `workspace/buildTargets`, `buildTarget/sources`, and `textDocument/sourceKitOption` requests should query the current state of the build server and return as quickly as possible to ensure smooth operation of SourceKit-LSP operations. Returning a response should not be blocked by expensive background computation. For example, if the BSP server receives a `workspace/buildTargets` request when it hasn’t computed a build graph yet, it is preferable that the build server returns an empty list of targets and sends a `buildTarget/didChange` notification when the build graph has been computed instead of waiting for build graph computation to finish before replying to the `workspace/buildTargets` request.
+
 If the build system does not have a notion of targets, eg. because it provides build settings from a file akin to a JSON compilation database, it may use a single dummy target for all source files or a separate target for each source file, either choice will work.
 
 If the build system loads the entire build graph during initialization, it may immediately return from `workspace/waitForBuildSystemUpdates`.