From f8a7cc678db857ac177e177020e2bc051822f9a5 Mon Sep 17 00:00:00 2001 From: Lukas Wirth Date: Thu, 15 Oct 2020 14:44:46 +0200 Subject: Document auto_import as a feature --- crates/assists/src/handlers/auto_import.rs | 55 ++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) 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. -- cgit v1.2.3