3 files changed, 59 insertions, 4 deletions

diff --git a/crates/assists/src/handlers/add_turbo_fish.rs b/crates/assists/src/handlers/add_turbo_fish.rs
index f4f997d8e..e3d84d698 100644
--- a/crates/assists/src/handlers/add_turbo_fish.rs
+++ b/crates/assists/src/handlers/add_turbo_fish.rs
@@ -1,4 +1,4 @@
-use ide_db::defs::{classify_name_ref, Definition, NameRefClass};
+use ide_db::defs::{Definition, NameRefClass};
 use syntax::{ast, AstNode, SyntaxKind, T};
 use test_utils::mark;
 
@@ -39,7 +39,7 @@ pub(crate) fn add_turbo_fish(acc: &mut Assists, ctx: &AssistContext) -> Option<(
         return None;
     }
     let name_ref = ast::NameRef::cast(ident.parent())?;
-    let def = match classify_name_ref(&ctx.sema, &name_ref)? {
+    let def = match NameRefClass::classify(&ctx.sema, &name_ref)? {
         NameRefClass::Definition(def) => def,
         NameRefClass::ExternCrate(_) | NameRefClass::FieldShorthand { .. } => return None,
     };
diff --git a/crates/assists/src/handlers/auto_import.rs b/crates/assists/src/handlers/auto_import.rs
index e595b5b93..4a7059c83 100644
--- a/crates/assists/src/handlers/auto_import.rs
+++ b/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.
diff --git a/crates/assists/src/handlers/expand_glob_import.rs b/crates/assists/src/handlers/expand_glob_import.rs
index d1adff972..316a58d88 100644
--- a/crates/assists/src/handlers/expand_glob_import.rs
+++ b/crates/assists/src/handlers/expand_glob_import.rs
@@ -1,7 +1,7 @@
 use either::Either;
 use hir::{AssocItem, MacroDef, Module, ModuleDef, Name, PathResolution, ScopeDef};
 use ide_db::{
-    defs::{classify_name_ref, Definition, NameRefClass},
+    defs::{Definition, NameRefClass},
     search::SearchScope,
 };
 use syntax::{
@@ -217,7 +217,7 @@ fn find_imported_defs(ctx: &AssistContext, star: SyntaxToken) -> Option<Vec<Def>
             .flatten()
             .filter_map(|n| Some(n.descendants().filter_map(ast::NameRef::cast)))
             .flatten()
-            .filter_map(|r| match classify_name_ref(&ctx.sema, &r)? {
+            .filter_map(|r| match NameRefClass::classify(&ctx.sema, &r)? {
                 NameRefClass::Definition(Definition::ModuleDef(def)) => Some(Def::ModuleDef(def)),
                 NameRefClass::Definition(Definition::Macro(def)) => Some(Def::MacroDef(def)),
                 _ => None,