Update some docs

Author: chenglou

.github/workflows/ci.yml

@@ -51,8 +51,8 @@ jobs:
     - run: npm run compile
 
     # These 2 runs (or just the second?) are for when you have opam dependencies. We don't.
-    # Don't add deps. But if you ever do, un-comment these
-    # - run: opam pin add rescript-editor-support.dev . --no-action
+    # Don't add deps. But if you ever do, un-comment these and add an .opam file.
+    # - run: opam pin add rescript-editor-analysis.dev . --no-action
     # - run: opam install . --deps-only --with-doc --with-test
 
     - name: Build and test

CHANGELOG.md

@@ -6,9 +6,9 @@ Fixes:
 - Hover on components in interface files.
 
 Features:
-- Show Outline
+- Show Outline!
 - Show References!
-- Hover now supports markdown docs!
+- Hover now supports markdown docs.
 - Hover on labels in component functions with compiler version 9.1, and labels with type annotation.
 - Don't show file path on hover and autocomplete (cleaner).
 - Autocomplete for props in JSX components.

CONTRIBUTING.md

@@ -17,6 +17,9 @@ Thanks for your interest. Below is an informal spec of how the plugin's server c
     ├── src
     │   └── server.ts // Language Server entry point
     └── analysis_binaries // Prod-time platform-specific analysis binaries
+        ├── darwin
+        ├── linux
+        └── win32
 ```
 
 ## Install Dependencies
@@ -31,6 +34,7 @@ Thanks for your interest. Below is an informal spec of how the plugin's server c
 - `cd analysis && make`.
 
 ## Test
+
 - Open VS Code to this folder.
 - Switch to the Debug viewlet (command palette -> View: Show Run and Debug).
 - Select `Client + Server` from the drop down, launch it (green arrow):
@@ -48,7 +52,7 @@ Thanks for your interest. Below is an informal spec of how the plugin's server c
   <img width="359" alt="image" src="https://user-images.githubusercontent.com/1909539/97448639-19db0800-18ee-11eb-875a-d17cd1b141d1.png">
 - For the native analysis binary tests: `cd analysis && make test`.
 
-### Change the Grammar
+## Change the Grammar
 
 The _real_ source of truth for our grammar is at https://github.com/rescript-lang/rescript-sublime. We port that `sublime-syntax` grammar over to this weaker TextMate language grammar for VSCode and the rest. There are some subtle differences between the 2 grammars; currently we manually sync between them.
 
@@ -58,14 +62,10 @@ For more grammar inspirations, check:
 - [TypeScript's grammar](https://github.com/microsoft/TypeScript-TmLanguage/blob/a771bc4e79deeae81a01d988a273e300290d0072/TypeScript.YAML-tmLanguage)
 - [Writing a TextMate Grammar: Some Lessons Learned](https://www.apeth.com/nonblog/stories/textmatebundle.html)
 
-### Snippets
+## Snippets
 
 Snippets are also synced from https://github.com/rescript-lang/rescript-sublime. VSCode snippets docs [here](https://code.visualstudio.com/api/references/contribution-points#contributes.snippets).
 
-### Autocomplete, Jump To Definition, Type Hint, Etc.
-
-These are taken care of by the binary at [rescript-editor-support](https://github.com/rescript-lang/rescript-editor-support). We just invoke it in `RescriptEditorSupport.ts`.
-
 ## Binary Invocation
 
 We call a few binaries and it's tricky to call them properly cross-platform. Here are some tips:
@@ -76,6 +76,10 @@ We call a few binaries and it's tricky to call them properly cross-platform. Her
 - `execFile` does not work on windows for batch scripts, which is what Node scripts are wrapped in. Use `exec`. See more [here](https://github.com/rescript-lang/rescript-vscode/blob/8fcc1ab428b8225c97d2c9a5b8e3a782c70d9439/server/src/utils.ts#L110).
 - Thankfully, many of our binaries are native, so we can keep using `execFile` most of the time.
 
+## General Coding Guidance
+
+- `server/` is a standalone folder that can be vendored by e.g. Vim and Sublime Text. Keep it light, don't add deps unless absolutely necessarily, and don't accidentally use a runtime dep from the top level `package.json`.
+
 ## Rough Description Of How The Plugin Works
 
 ### Editor Diagnostics
@@ -167,3 +171,5 @@ Currently the release is vetted and done by @chenglou.
 - Download and unzip the 3 platforms' production binaries from the Github CI. Put them into `server/analysis_binaries`.
 - Use `vsce publish` to publish. Official VSCode guide [here](https://code.visualstudio.com/api/working-with-extensions/publishing-extension). Only @chenglou has the publishing rights right now.
 - Not done! Make a new manual release [here](https://github.com/rescript-lang/rescript-vscode/releases); use `vsce package` to package up a standalone `.vsix` plugin and attach it onto that new release. This is for folks who don't use the VSCode marketplace.
+
+For beta releases, we just do the last step and ask folks to try it.

analysis/src/Cli.ml

@@ -2,31 +2,30 @@ let help =
   {|
 **Private CLI For rescript-vscode usage only**
 
-Examples:
+API examples:
   ./rescript-editor-analysis.exe complete src/MyFile.res 0 4 currentContent.res
   ./rescript-editor-analysis.exe definition src/MyFile.res 9 3
-  ./rescript-editor-analysis.exe dump src/MyFile.res src/MyFile2.res
   ./rescript-editor-analysis.exe documentSymbol src/Foo.res
   ./rescript-editor-analysis.exe hover src/MyFile.res 10 2
   ./rescript-editor-analysis.exe references src/MyFile.res 10 2
+
+Dev-time examples:
+  ./rescript-editor-analysis.exe dump src/MyFile.res src/MyFile2.res
   ./rescript-editor-analysis.exe test src/MyFile.res
 
-Note: coordinates are zero-based, so the first position is 0 0.
+Note: positions are zero-indexed (start at 0 0), following LSP.
+https://microsoft.github.io/language-server-protocol/specification#position
 
 Options:
-  complete: compute autocomplete for MyFile.res at line 0 and column 4,
+  completion: compute autocomplete for MyFile.res at line 0 and column 4,
     where MyFile.res is being edited and the editor content is in file current.res.
 
-    ./rescript-editor-analysis.exe complete src/MyFile.res 0 4 current.res
+    ./rescript-editor-analysis.exe completion src/MyFile.res 0 4 current.res
 
   definition: get definition for item in MyFile.res at line 10 column 2:
 
     ./rescript-editor-analysis.exe definition src/MyFile.res 10 2
 
-  dump: for debugging, show all definitions and hovers for MyFile.res and MyFile.res:
-
-    ./rescript-editor-analysis.exe dump src/Foo.res src/MyFile.res
-
   documentSymbol: get all symbols declared in MyFile.res
 
     ./rescript-editor-analysis.exe documentSymbol src/MyFile.res
@@ -39,15 +38,19 @@ Options:
 
     ./rescript-editor-analysis.exe references src/MyFile.res 10 2
 
+  dump: for debugging, show all definitions and hovers for MyFile.res and MyFile.res:
+
+    ./rescript-editor-analysis.exe dump src/Foo.res src/MyFile.res
+
   test: run tests specified by special comments in file src/MyFile.res
 
   ./rescript-editor-analysis.exe test src/src/MyFile.res
 |}
 
 let main () =
   match Array.to_list Sys.argv with
-  | [_; "complete"; path; line; col; currentFile] ->
-    Commands.complete ~path ~line:(int_of_string line) ~col:(int_of_string col)
+  | [_; "completion"; path; line; col; currentFile] ->
+    Commands.completion ~path ~line:(int_of_string line) ~col:(int_of_string col)
       ~currentFile
   | [_; "definition"; path; line; col] ->
     Commands.definition ~path ~line:(int_of_string line)

analysis/src/Commands.ml

@@ -33,7 +33,7 @@ let dump files =
          in
          print_endline result)
 
-let complete ~path ~line ~col ~currentFile =
+let completion ~path ~line ~col ~currentFile =
   let uri = Uri2.fromLocalPath path in
   let result =
     match ProcessCmt.getFullFromCmt ~uri with
@@ -239,7 +239,7 @@ let test ~path =
             let line = line + 1 in
             let col = len - mlen - 3 in
             close_out cout;
-            complete ~path ~line ~col ~currentFile;
+            completion ~path ~line ~col ~currentFile;
             Sys.remove currentFile
           | _ -> ());
           print_newline ())