Document auto_import as a feature

Author: Veykril

crates/assists/src/handlers/auto_import.rs

@@ -6,6 +6,61 @@ use crate::{
     AssistContext, AssistId, AssistKind, Assists, GroupLabel,
 };
 
+// Feature: Import Insertion
+//
+// Using the `auto-import` assist it is possible to insert missing imports for unresolved items.
+// When inserting an import it will do so in a structured manner by keeping imports grouped,
+// separated by a newline in the following order:
+//
+// - `std` and `core`
+// - External Crates
+// - Current Crate, paths prefixed by `crate`
+// - Current Module, paths prefixed by `self`
+// - Super Module, paths prefixed by `super`
+//
+// Example:
+// ```rust
+// use std::fs::File;
+//
+// use itertools::Itertools;
+// use syntax::ast;
+//
+// use crate::utils::insert_use;
+//
+// use self::auto_import;
+//
+// use super::AssistContext;
+// ```
+//
+// .Merge Behaviour
+//
+// It is possible to configure how use-trees are merged with the `importMergeBehaviour` setting.
+// It has the following configurations:
+//
+// - `full`: This setting will cause auto-import to always completely merge use-trees that share the
+//  same path prefix while also merging inner trees that share the same path-prefix. This kind of
+//  nesting is only supported in Rust versions later than 1.24.
+// - `last`: This setting will cause auto-import to merge use-trees as long as the resulting tree
+//  will only contain a nesting of single segment paths at the very end.
+// - `none`: This setting will cause auto-import to never merge use-trees keeping them as simple
+//  paths.
+//
+// In `VS Code` the configuration for this is `rust-analyzer.assist.importMergeBehaviour`.
+//
+// .Import Prefix
+//
+// The style of imports in the same crate is configurable through the `importPrefix` setting.
+// It has the following configurations:
+//
+// - `by_crate`: This setting will force paths to be always absolute, starting with the `crate`
+//  prefix, unless the item is defined outside of the current crate.
+// - `by_self`: This setting will force paths that are relative to the current module to always
+//  start with `self`. This will result in paths that always start with either `crate`, `self`,
+//  `super` or an extern crate identifier.
+// - `plain`: This setting does not impose any restrictions in imports.
+//
+// In `VS Code` the configuration for this is `rust-analyzer.assist.importPrefix`.
+
 // Assist: auto_import
 //
 // If the name is unresolved, provides all possible imports for it.