Merge #4664

4664: Generate feature documentation from code r=matklad a=matklad



Co-authored-by: Aleksey Kladov <[email protected]>

Author: bors[bot]

.gitignore

@@ -7,4 +7,4 @@ crates/*/target
 *.log
 *.iml
 .vscode/settings.json
-cargo-timing*.html
+*.html

crates/ra_assists/src/handlers/add_from_impl_for_enum.rs

@@ -4,9 +4,9 @@ use test_utils::mark;
 
 use crate::{utils::FamousDefs, AssistContext, AssistId, Assists};
 
-// Assist add_from_impl_for_enum
+// Assist: add_from_impl_for_enum
 //
-// Adds a From impl for an enum variant with one tuple field
+// Adds a From impl for an enum variant with one tuple field.
 //
 // ```
 // enum A { <|>One(u32) }

crates/ra_assists/src/tests/generated.rs

@@ -58,6 +58,25 @@ fn main() {
     )
 }
 
+#[test]
+fn doctest_add_from_impl_for_enum() {
+    check_doc_test(
+        "add_from_impl_for_enum",
+        r#####"
+enum A { <|>One(u32) }
+"#####,
+        r#####"
+enum A { One(u32) }
+
+impl From<u32> for A {
+    fn from(v: u32) -> Self {
+        A::One(v)
+    }
+}
+"#####,
+    )
+}
+
 #[test]
 fn doctest_add_function() {
     check_doc_test(

crates/ra_ide/src/completion.rs

@@ -1,5 +1,3 @@
-//! FIXME: write short doc here
-
 mod completion_config;
 mod completion_item;
 mod completion_context;
@@ -35,6 +33,51 @@ pub use crate::completion::{
     completion_item::{CompletionItem, CompletionItemKind, CompletionScore, InsertTextFormat},
 };
 
+//FIXME: split the following feature into fine-grained features.
+
+// Feature: Magic Completions
+//
+// In addition to usual reference completion, rust-analyzer provides some ✨magic✨
+// completions as well:
+//
+// Keywords like `if`, `else` `while`, `loop` are completed with braces, and cursor
+// is placed at the appropriate position. Even though `if` is easy to type, you
+// still want to complete it, to get ` { }` for free! `return` is inserted with a
+// space or `;` depending on the return type of the function.
+//
+// When completing a function call, `()` are automatically inserted. If a function
+// takes arguments, the cursor is positioned inside the parenthesis.
+//
+// There are postfix completions, which can be triggered by typing something like
+// `foo().if`. The word after `.` determines postfix completion. Possible variants are:
+//
+// - `expr.if` -> `if expr {}` or `if let ... {}` for `Option` or `Result`
+// - `expr.match` -> `match expr {}`
+// - `expr.while` -> `while expr {}` or `while let ... {}` for `Option` or `Result`
+// - `expr.ref` -> `&expr`
+// - `expr.refm` -> `&mut expr`
+// - `expr.not` -> `!expr`
+// - `expr.dbg` -> `dbg!(expr)`
+//
+// There also snippet completions:
+//
+// .Expressions
+// - `pd` -> `println!("{:?}")`
+// - `ppd` -> `println!("{:#?}")`
+//
+// .Items
+// - `tfn` -> `#[test] fn f(){}`
+// - `tmod` ->
+// ```rust
+// #[cfg(test)]
+// mod tests {
+//     use super::*;
+//
+//     #[test]
+//     fn test_fn() {}
+// }
+// ```
+
 /// Main entry point for completion. We run completion as a two-phase process.
 ///
 /// First, we look at the position and collect a so-called `CompletionContext.

crates/ra_ide/src/completion/complete_postfix.rs

@@ -1,20 +1,20 @@
 //! FIXME: write short doc here
-
+use ra_assists::utils::TryEnum;
 use ra_syntax::{
     ast::{self, AstNode},
     TextRange, TextSize,
 };
 use ra_text_edit::TextEdit;
 
-use super::completion_config::SnippetCap;
 use crate::{
     completion::{
         completion_context::CompletionContext,
         completion_item::{Builder, CompletionKind, Completions},
     },
     CompletionItem,
 };
-use ra_assists::utils::TryEnum;
+
+use super::completion_config::SnippetCap;
 
 pub(super) fn complete_postfix(acc: &mut Completions, ctx: &CompletionContext) {
     if !ctx.config.enable_postfix_completions {

crates/ra_ide/src/display/structure.rs

@@ -1,10 +1,6 @@
-//! FIXME: write short doc here
-
-use crate::TextRange;
-
 use ra_syntax::{
     ast::{self, AttrsOwner, NameOwner, TypeAscriptionOwner, TypeParamsOwner},
-    match_ast, AstNode, SourceFile, SyntaxKind, SyntaxNode, WalkEvent,
+    match_ast, AstNode, SourceFile, SyntaxKind, SyntaxNode, TextRange, WalkEvent,
 };
 
 #[derive(Debug, Clone)]
@@ -18,6 +14,19 @@ pub struct StructureNode {
     pub deprecated: bool,
 }
 
+// Feature: File Structure
+//
+// Provides a tree of the symbols defined in the file. Can be used to
+//
+// * fuzzy search symbol in a file (super useful)
+// * draw breadcrumbs to describe the context around the cursor
+// * draw outline of the file
+//
+// |===
+// | Editor  | Shortcut
+//
+// | VS Code | kbd:[Ctrl+Shift+O]
+// |===
 pub fn file_structure(file: &SourceFile) -> Vec<StructureNode> {
     let mut res = Vec::new();
     let mut stack = Vec::new();

crates/ra_ide/src/expand_macro.rs

@@ -1,5 +1,3 @@
-//! This modules implements "expand macro" functionality in the IDE
-
 use hir::Semantics;
 use ra_ide_db::RootDatabase;
 use ra_syntax::{
@@ -14,6 +12,15 @@ pub struct ExpandedMacro {
     pub expansion: String,
 }
 
+// Feature: Expand Macro Recursively
+//
+// Shows the full macro expansion of the macro at current cursor.
+//
+// |===
+// | Editor  | Action Name
+//
+// | VS Code | **Rust Analyzer: Expand macro recursively**
+// |===
 pub(crate) fn expand_macro(db: &RootDatabase, position: FilePosition) -> Option<ExpandedMacro> {
     let sema = Semantics::new(db);
     let file = sema.parse(position.file_id);

crates/ra_ide/src/extend_selection.rs

@@ -1,5 +1,3 @@
-//! FIXME: write short doc here
-
 use std::iter::successors;
 
 use hir::Semantics;
@@ -14,6 +12,16 @@ use ra_syntax::{
 
 use crate::FileRange;
 
+// Feature: Extend Selection
+//
+// Extends the current selection to the encompassing syntactic construct
+// (expression, statement, item, module, etc). It works with multiple cursors.
+//
+// |===
+// | Editor  | Shortcut
+//
+// | VS Code | kbd:[Ctrl+Shift+→]
+// |===
 pub(crate) fn extend_selection(db: &RootDatabase, frange: FileRange) -> TextRange {
     let sema = Semantics::new(db);
     let src = sema.parse(frange.file_id);

crates/ra_ide/src/goto_definition.rs

@@ -1,5 +1,3 @@
-//! FIXME: write short doc here
-
 use hir::Semantics;
 use ra_ide_db::{
     defs::{classify_name, classify_name_ref},
@@ -17,6 +15,15 @@ use crate::{
     FilePosition, NavigationTarget, RangeInfo,
 };
 
+// Feature: Go to Definition
+//
+// Navigates to the definition of an identifier.
+//
+// |===
+// | Editor  | Shortcut
+//
+// | VS Code | kbd:[F12]
+// |===
 pub(crate) fn goto_definition(
     db: &RootDatabase,
     position: FilePosition,

crates/ra_ide/src/impls.rs renamed to crates/ra_ide/src/goto_implementation.rs

@@ -1,11 +1,18 @@
-//! FIXME: write short doc here
-
 use hir::{Crate, ImplDef, Semantics};
 use ra_ide_db::RootDatabase;
 use ra_syntax::{algo::find_node_at_offset, ast, AstNode};
 
 use crate::{display::ToNav, FilePosition, NavigationTarget, RangeInfo};
 
+// Feature: Go to Implementation
+//
+// Navigates to the impl block of structs, enums or traits. Also implemented as a code lens.
+//
+// |===
+// | Editor  | Shortcut
+//
+// | VS Code | kbd:[Ctrl+F12]
+// |===
 pub(crate) fn goto_implementation(
     db: &RootDatabase,
     position: FilePosition,