Added documentation (editor-rs#68)

CONTRIBUTING.md

@@ -2,6 +2,7 @@ There are several sections.
 Choose one of them and follow the instructions.
 
 # Open an issue
+
 Use this section if you want to open an issue describing a problem.
 
 Please follow the instructions:
@@ -10,6 +11,7 @@ Please follow the instructions:
 * Fill the issue
 
 # Fix an opened issue
+
 Use this section if you want to fix a problem or add a feature and there is an opened issue for that.
 
 Please follow the instructions:
@@ -27,6 +29,7 @@ Please follow the instructions:
 * Wait until the pull request is merged
 
 # Fix a bug or add a feature
+
 Use this section if you want to fix a problem or add a feature and there is no opened issue for that.
 
 Please follow the instructions:
@@ -36,6 +39,7 @@ Please follow the instructions:
 * Follow the instructions from the section "Fix an opened issue"
 
 # Suggestion to add a feature or change behavior
+
 Use this section if you have an idea, but you are unsure whether other people would like it.
 
 Please follow the instructions:
@@ -44,6 +48,7 @@ Please follow the instructions:
 * Discuss it
 
 # Instruction to be done before submitting a pull question
+
 * Execute `npm run gulp` in the root directory of the extension to compile the code and to check for code style violation
 * Launch tests:
   * Open the project in VSCode

README.md

@@ -6,93 +6,39 @@
 # Rust for Visual Studio Code (Latest: 0.3.6)
 
 ## Why this fork
+
 The maintainer of RustyCode doesn't answer.
 
 The repo contains a lot of bug fixes and new features.
 
 ## Extension
+
 On update please look at the change log.
 
 [Changelog](CHANGELOG.md)
 
+[Documentation](doc/main.md)
+
 [Contributing](CONTRIBUTING.md)
 
 [Roadmap](ROADMAP.md)
 
 This extension adds advanced language support for the Rust language to VS Code, including:
 
-- Autocompletion (using `racer`)
-- Go To Definition (using `racer`)
-- Go To Symbol (using `rustsym`)
+- Autocompletion (using `racer` or `Rust Language Server`)
+- Go To Definition (using `Rust Language Server` or `Rust Language Server`)
+- Go To Symbol (using `rustsym` or `Rust Language Server`)
 - Format (using `rustfmt`)
-- Linter. Linting can be done via:
-	- `check`. This is the default. Runs rust compiler but skips codegen pass.
-	- `clippy` if `cargo-clippy` is installed
-	- `build`
-- Cargo tasks (Open Command Pallete and they will be there)
+- Cargo tasks (Open the Command Palette and they will be there)
 - Snippets
+- And a lot of other features, to read about them, read the [documentation](doc/main.md).
 
+## Installation
 
-### IDE Features
-![IDE](images/ide_features.png)
-
-## Using
-
-First, you will need to install Visual Studio Code `1.8` or newer. In the command pallete (`cmd-shift-p`) select `Install Extension` and choose `Rust`.
-
-This extension uses the following applications:
-
-* racer
-* rustsym
-* rustfmt
-
-All this applications can be installed by youself and by VSCode.
-
-In order to install them in VSCode, Open any *.rs file and click on the button "Rust Tools Missing" at the right bottom corner.
-
-**racer** uses source files to provide autocompletion. Install them to your computer to use **racer**.
+First, you will need to install Visual Studio Code `1.8` or newer.
 
-### Options
-
-The following Visual Studio Code settings are available for the Rust extension. These can be set in user preferences or workspace settings (`.vscode/settings.json`)
-
-```javascript
-{
-	"rust.racerPath": null, // Specifies path to Racer binary if it's not in PATH
-	"rust.rustLangSrcPath": null, // Specifies path to /src directory of local copy of Rust sources
-	"rust.rustfmtPath": null, // Specifies path to Rustfmt binary if it's not in PATH
-	"rust.rustsymPath": null, // Specifies path to Rustsym binary if it's not in PATH
-	"rust.cargoPath": null, // Specifies path to Cargo binary if it's not in PATH
-	"rust.cargoHomePath": null, // Path to Cargo home directory, mostly needed for racer. Needed only if using custom rust installation.
-	"rust.cargoEnv": null, // Specifies custom variables to set when running cargo. Useful for crates which use env vars in their build.rs (like openssl-sys).
-	"rust.formatOnSave": false, // Turn on/off autoformatting file on save (EXPERIMENTAL)
-	"rust.checkOnSave": false, // Turn on/off `cargo check` project on save (EXPERIMENTAL)
-	"rust.checkWith": "build", // Specifies the linter to use. (EXPERIMENTAL)
-	"rust.useJsonErrors": false, // Enable the use of JSON errors (requires Rust 1.7+). Note: This is an unstable feature of Rust and is still in the process of being stablised
-	"rust.useNewErrorFormat": false, // "Use the new Rust error format (RUST_NEW_ERROR_FORMAT=true). Note: This flag is mutually exclusive with `useJsonErrors`.
-}
-```
-
-## Building and Debugging the Extension
-
-[Repository](https://github.com/KalitaAlexey/vscode-rust)
-
-You can set up a development enviroment for debugging the extension during extension development.
-
-First make sure you do not have the extension installed in `~/.vscode/extensions`. Then clone the repo somewhere else on your machine, run `npm install` and open a development instance of Code.
-
-```bash
-rm -rf ~/.vscode/extensions/vscode-rust
-cd ~
-git clone https://github.com/KalitaAlexey/vscode-rust
-cd vscode-rust
-npm install
-npm run-script compile
-code .
-```
-
-You can now go to the Debug viewlet and select `Launch Extension` then hit run (`F5`).
-If you make edits in the extension `.ts` files, just reload (`cmd-r`) the `[Extension Development Host]` instance of Code to load in the new extension code.  The debugging instance will automatically reattach.
+In the command palette (`cmd-shift-p`) select `Install Extension` and choose `Rust`.
 
 ## License
+
 [MIT](LICENSE)

doc/cargo_command_execution.md

@@ -0,0 +1,199 @@
+# Cargo Command Execution Page
+
+The extension allows a developer to execute any of built-in cargo commands.
+
+These commands are:
+
+* bench
+* build
+* check
+* clean
+* clippy
+* doc
+* new
+* run
+* test
+* update
+
+These commands available through the command palette (CTRL+P).
+
+These commands have prefix `"Cargo: "`.
+
+## Execute Command On Save
+
+The extension supports executing a command after saving the document opened in the active text document.
+
+The `"rust.actionOnSave"` configuration parameter specifies a command to execute.
+
+The possible values:
+
+* `"build"` - the extension executes `"Cargo: Build"`
+* `"check"` - the extension executes `"Cargo: Check"`
+* `"clippy"` - the extension executes `"Cargo: Clippy"`
+* `"run"` - the extension executes `"Cargo: Run"`
+* `"test"` - the extension executes `"Cargo: Test"`
+* `null` - the extension does nothing
+
+By default, it is `null`.
+
+## Current Working Directory Determination
+
+The extension executes a cargo command in some directory. To find out which directory the extension should use, the extension uses the following algorithm:
+
+* Try making out the current working directory from the active text editor
+
+  If all of the conditions are met:
+
+    * There is an active text editor
+    * A file opened in the editor is in the workspace (the opened directory)
+    * There is a `Cargo.toml` file near the file or in the parent directories within the workspace
+
+  Then use the directory containing the `Cargo.toml` file.
+
+* Try using the previous current working directory
+* Try using the workspace
+
+## Configuration Parameters
+
+### Cargo Path
+
+The `"rust.cargoPath"` configuration parameter specifies a path to the cargo's executable.
+
+The possible values:
+
+* `"Some path"` - the extension would try to use the path
+* `null` - the extension would try to use cargo from the `PATH` variable of the environment.
+
+If cargo isn't available the extension can't execute a cargo command.
+
+### Cargo Environment
+
+The `"rust.cargoEnv"` configuration parameter specifies an environment which would be added to the general environment for executing a cargo command.
+
+The possible values:
+
+* Some object (`{ "RUST_BACKTRACE": 1 }`)
+* `null`
+
+### Passing Arguments
+
+The extension supports several configuration parameters:
+
+* `"rust.buildArgs"`
+* `"rust.checkArgs"`
+* `"rust.clippyArgs"`
+* `"rust.runArgs"`
+* `"rust.testArgs"`
+
+The type of these configuration parameters is an array of strings.
+
+These configuration parameters specify arguments which are passed to an appropriate command.
+
+It is useful when you want the extension to execute `cargo build --features some_feature`.
+
+These configuration parameters are used when one of the following commands is invoked:
+
+* `"Cargo: Build"`
+* `"Cargo: Check"`
+* `"Cargo: Clippy"`
+* `"Cargo: Run"`
+* `"Cargo: Test"`
+
+#### Examples
+
+```json
+"rust.buildArgs": ["--features", "some_feature"]
+```
+
+### Custom Configurations
+
+The extension supports several configuration parameters:
+
+* `"rust.customBuildConfigurations"`
+* `"rust.customCheckConfigurations"`
+* `"rust.customClippyConfigurations"`
+* `"rust.customRunConfigurations"`
+* `"rust.customTestConfigurations"`
+
+The type of these configuration parameters is an array of objects.
+The object must have the following fields:
+
+* `"title"` - a string. It is shown as the label of a quick pick item if a cargo command has several custom configurations
+* `"args"` - an array of strings. If a custom configuration is chosen, a cargo command is executed with the arguments from the custom configuration
+
+These configuration parameters are used when one of the following commands is invoked:
+
+* `"Cargo: Build using custom configuration"`
+* `"Cargo: Check using custom configuration"`
+* `"Cargo: Clippy using custom configuration"`
+* `"Cargo: Run using custom configuration"`
+* `"Cargo: Test using custom configuration"`
+
+If any of the following commands is invoked, the extension decides what to do.
+
+If none of the custom configurations for the command is defined the extension shows an error message.
+
+If only one custom configuration for the command is defined the extension executes the command with the arguments from the custom configuration.
+
+If many custom configurations for the command are defined the extension shows a quick pick with titles of the custom configurations to let a developer decide.
+
+If a developer cancels the quick pick the extension does nothing.
+
+If a developer chooses an item the extension executes the command with the arguments from the chosen configuration.
+
+#### Examples
+
+##### Build Example
+
+```json
+"rust.customBuildConfigurations": [
+  {
+    "title": "Example: my_example",
+    "args": ["--example", "my_example"]
+  }
+]
+```
+
+##### Check With Features
+
+```json
+"rust.customCheckConfigurations": [
+  {
+    "title": "With Features",
+    "args": ["--features", "feature1", "feature2"]
+  }
+]
+```
+
+##### Clippy With Features
+
+```json
+"rust.customClippyConfigurations": [
+  {
+    "title": "With Features",
+    "args": ["--features", "feature1", "feature2"]
+  }
+]
+```
+
+##### Run With Arguments
+
+```json
+"rust.customRunConfigurations": [
+  {
+    "title": "With Arguments",
+    "args": ["--", "arg1", "arg2"]
+  }
+]
+```
+
+##### Test No Run
+
+```json
+"rust.customTestConfigurations": [
+  {
+    "title": "No Run",
+    "args": ["--no-run"]
+  }
+]
+```

doc/format.md

@@ -0,0 +1,19 @@
+# Format Page
+
+The extension supports formatting the document opened in the active text editor on saving.
+
+If the extension is runnning in [RLS Mode](rls_mode.md), formatting is performed via `rustfmt` integrated into RLS.
+
+If the extension is running in [Legacy Mode](legacy_mode/main.md), formatting is performed via separate `rustfmt`.
+
+Read more about [rustfmt configuration](legacy_mode/rustfmt_configuration.md) for Legacy Mode.
+
+In order to format the document, make a right click and choose `"Format Document"`.
+
+## Format On Save
+
+The extension supports formatting the document opened in the active text editor on saving.
+
+The `"rust.formatOnSave"` specifies whether the extension should format the active document on save.
+
+By default, it is `false`.