Address review comments

Author: Duhemm

docs/docs/usage/worksheet-mode-implementation-details.md

@@ -0,0 +1,79 @@
+---
+layout: doc-page
+title: "Worksheet Mode - Implementation details"
+---
+
+In brief, the worksheets extend the Language Server Protocol and rely on the
+Dotty REPL to evaluate code.
+
+## Evaluation
+Each of the individual expressions and statements of the worksheet is extracted
+and passed to the Dotty REPL. After the REPL has finished evaluating one unit of
+input, it emits a special delimiter that indicates the end of the output for
+this input. (See `dotty.tools.languageserver.worksheet.InputStreamConsumer`)
+
+This process continues until all input has been evaluated.
+
+The Dotty REPL is run in a separate JVM. The `Evaluator` (see
+`dotty.tools.languageserver.worksheet.Evaluator`) will re-use a JVM if the
+configuration of the project hasn't changed.
+
+## Communication with the client
+The worksheets extend the Language Server Protocol and add one request and one
+notification.
+
+### Run worksheet request
+The worksheet run request is sent from the client to the server to request that
+the server runs a given worksheet and streams the result.
+
+*Request:*
+
+ - method: `worksheet/run`
+ - params: `WorksheetRunParams` defined as follows:
+   ```typescript
+   interface WorksheetRunParams {
+       /**
+        * The worksheet to evaluate.
+        */
+       textDocument: VersionedTextDocumentIdentifier;
+   }
+   ```
+
+*Response:*
+
+ - result: `WorksheetRunResult` defined as follows:
+   ```typescript
+   interface WorksheetRunResult {
+       /**
+        * Indicates whether evaluation was successful.
+        */
+       success: boolean;
+   }
+   ```
+
+### Worksheet output notification
+The worksheet output notification is sent from the server to the client to
+indicate that worksheet execution has produced some output.
+
+*Notification:*
+
+ - method: `worksheet/publishOutput`
+ - params: `WorksheetRunOutput` defined as follows:
+   ```typescript
+   interface WorksheetRunOutput {
+       /**
+        * The worksheet that produced this output.
+        */
+       textDocument: VersionedTextDocumentIdentifier;
+   
+       /**
+        * The line number of the expression that produced this output.
+        */
+       line: int;
+   
+       /**
+        * The output that has been produced.
+        */
+       content: string;
+   }
+   ```

docs/docs/usage/worksheet-mode.md

@@ -31,6 +31,11 @@ project and its dependencies on their classpath.
 
 ![](../../images/worksheets/worksheet-run.png "Run worksheet")
 
+By default, the worksheets are also run when the file is saved. This can be
+configured in VSCode preferences:
+
+![](../../images/worksheets/config-autorun.png "Configure run on save")
+
 Note that the worksheet are fully integrated with the rest of Dotty IDE: While
 typing, errors are shown, completions are suggested, and you can use all the
 other features of Dotty IDE such as go to definition, find all references, etc.
@@ -40,77 +45,6 @@ other features of Dotty IDE such as go to definition, find all references, etc.
 Implementation details
 ======================
 
-In overview, the worksheets extend the Language Server Protocol and rely on the
-Dotty REPL to evaluate code.
-
-## Evaluation
-Each of the individual expressions and statements of the worksheet is extracted
-and passed to the Dotty REPL. After the REPL has finished evaluating one unit of
-input, it emits a special delimiter that indicates the end of the output for
-this input. (See `dotty.tools.languageserver.worksheet.InputStreamConsumer`)
-
-This process continues until all input has been evaluated.
-
-The Dotty REPL is run in a separate JVM. The `Evaluator` (see
-`dotty.tools.languageserver.worksheet.Evaluator`) will re-use a JVM if the
-configuration of the project hasn't changed.
-
-## Communication with the client
-The worksheets extend the Language Server Protocol and add one request and one
-notification.
-
-### Run worksheet request
-The worksheet run request is sent from the client to the server to request that
-the server runs a given worksheet and streams the result.
-
-*Request:*
-
- - method: `worksheet/run`
- - params: `WorksheetRunParams` defined as follows:
-   ```typescript
-   interface WorksheetRunParams {
-       /**
-        * The worksheet to evaluate.
-        */
-       textDocument: VersionedTextDocumentIdentifier;
-   }
-   ```
-
-*Response:*
-
- - result: `WorksheetRunResult` defined as follows:
-   ```typescript
-   interface WorksheetRunResult {
-       /**
-        * Indicates whether evaluation was successful.
-        */
-       success: boolean;
-   }
-   ```
-
-### Worksheet output notification
-The worksheet output notification is sent from the server to the client to
-indicate that worksheet execution has produced some output.
-
-*Notification:*
-
- - method: `worksheet/publishOutput`
- - params: `WorksheetRunOutput` defined as follows:
-   ```typescript
-   interface WorksheetRunOutput {
-       /**
-        * The worksheet that produced this output.
-        */
-       textDocument: VersionedTextDocumentIdentifier;
-   
-       /**
-        * The line number of the expression that produced this output.
-        */
-       line: int;
-   
-       /**
-        * The output that has been produced.
-        */
-       content: string;
-   }
-   ```
+The implementation details of the worksheet mode and the information necessary to add support for
+other clients are available in [Worksheet mode - Implementation
+details](worksheet-mode-implementation-details.html).