1 files changed, 62 insertions, 28 deletions

diff --git a/crates/ra_analysis/src/lib.rs b/crates/ra_analysis/src/lib.rs
index efb483103..b4669dfff 100644
--- a/crates/ra_analysis/src/lib.rs
+++ b/crates/ra_analysis/src/lib.rs
@@ -148,27 +148,6 @@ impl AnalysisChange {
     }
 }
 
-/// `AnalysisHost` stores the current state of the world.
-#[derive(Debug, Default)]
-pub struct AnalysisHost {
-    db: db::RootDatabase,
-}
-
-impl AnalysisHost {
-    /// Returns a snapshot of the current state, which you can query for
-    /// semantic information.
-    pub fn analysis(&self) -> Analysis {
-        Analysis {
-            db: self.db.snapshot(),
-        }
-    }
-    /// Applies changes to the current state of the world. If there are
-    /// outstanding snapshots, they will be canceled.
-    pub fn apply_change(&mut self, change: AnalysisChange) {
-        self.db.apply_change(change)
-    }
-}
-
 #[derive(Debug)]
 pub struct SourceChange {
     pub label: String,
@@ -285,6 +264,27 @@ impl ReferenceResolution {
     }
 }
 
+/// `AnalysisHost` stores the current state of the world.
+#[derive(Debug, Default)]
+pub struct AnalysisHost {
+    db: db::RootDatabase,
+}
+
+impl AnalysisHost {
+    /// Returns a snapshot of the current state, which you can query for
+    /// semantic information.
+    pub fn analysis(&self) -> Analysis {
+        Analysis {
+            db: self.db.snapshot(),
+        }
+    }
+    /// Applies changes to the current state of the world. If there are
+    /// outstanding snapshots, they will be canceled.
+    pub fn apply_change(&mut self, change: AnalysisChange) {
+        self.db.apply_change(change)
+    }
+}
+
 /// Analysis is a snapshot of a world state at a moment in time. It is the main
 /// entry point for asking semantic information about the world. When the world
 /// state is advanced using `AnalysisHost::apply_change` method, all existing
@@ -295,107 +295,141 @@ pub struct Analysis {
 }
 
 impl Analysis {
+    /// Gets the text of the source file.
     pub fn file_text(&self, file_id: FileId) -> Arc<String> {
         self.db.file_text(file_id)
     }
+    /// Gets the syntax tree of the file.
     pub fn file_syntax(&self, file_id: FileId) -> SourceFileNode {
         self.db.source_file(file_id).clone()
     }
+    /// Gets the file's `LineIndex`: data structure to convert between absolute
+    /// offsets and line/column representation.
     pub fn file_line_index(&self, file_id: FileId) -> Arc<LineIndex> {
         self.db.file_lines(file_id)
     }
+    /// Selects the next syntactic nodes encopasing the range.
     pub fn extend_selection(&self, frange: FileRange) -> TextRange {
         extend_selection::extend_selection(&self.db, frange)
     }
+    /// Returns position of the mathcing brace (all types of braces are
+    /// supported).
     pub fn matching_brace(&self, file: &SourceFileNode, offset: TextUnit) -> Option<TextUnit> {
         ra_editor::matching_brace(file, offset)
     }
+    /// Returns a syntax tree represented as `String`, for debug purposes.
+    // FIXME: use a better name here.
     pub fn syntax_tree(&self, file_id: FileId) -> String {
         let file = self.db.source_file(file_id);
         ra_editor::syntax_tree(&file)
     }
+    /// Returns an edit to remove all newlines in the range, cleaning up minor
+    /// stuff like trailing commas.
     pub fn join_lines(&self, frange: FileRange) -> SourceChange {
         let file = self.db.source_file(frange.file_id);
         SourceChange::from_local_edit(frange.file_id, ra_editor::join_lines(&file, frange.range))
     }
+    /// Returns an edit which should be applied when opening a new line, fixing
+    /// up minor stuff like continuing the comment.
     pub fn on_enter(&self, position: FilePosition) -> Option<SourceChange> {
         let file = self.db.source_file(position.file_id);
         let edit = ra_editor::on_enter(&file, position.offset)?;
-        let res = SourceChange::from_local_edit(position.file_id, edit);
-        Some(res)
+        Some(SourceChange::from_local_edit(position.file_id, edit))
     }
+    /// Returns an edit which should be applied after `=` was typed. Primaraly,
+    /// this works when adding `let =`.
+    // FIXME: use a snippet completion instead of this hack here.
     pub fn on_eq_typed(&self, position: FilePosition) -> Option<SourceChange> {
         let file = self.db.source_file(position.file_id);
-        Some(SourceChange::from_local_edit(
-            position.file_id,
-            ra_editor::on_eq_typed(&file, position.offset)?,
-        ))
+        let edit = ra_editor::on_eq_typed(&file, position.offset)?;
+        Some(SourceChange::from_local_edit(position.file_id, edit))
     }
+    /// Returns a tree representation of symbols in the file. Useful to draw a
+    /// file outline.
     pub fn file_structure(&self, file_id: FileId) -> Vec<StructureNode> {
         let file = self.db.source_file(file_id);
         ra_editor::file_structure(&file)
     }
+    /// Returns the set of folding ranges.
     pub fn folding_ranges(&self, file_id: FileId) -> Vec<Fold> {
         let file = self.db.source_file(file_id);
         ra_editor::folding_ranges(&file)
     }
+    /// Fuzzy searches for a symbol.
     pub fn symbol_search(&self, query: Query) -> Cancelable<Vec<NavigationTarget>> {
-        let res = symbol_index::world_symbols(&*self.db, query)?
+        let res = symbol_index::world_symbols(self.db, query)?
             .into_iter()
             .map(|(file_id, symbol)| NavigationTarget { file_id, symbol })
             .collect();
         Ok(res)
     }
+    /// Resolves reference to definition, but does not gurantee correctness.
     pub fn approximately_resolve_symbol(
         &self,
         position: FilePosition,
     ) -> Cancelable<Option<ReferenceResolution>> {
         self.db.approximately_resolve_symbol(position)
     }
+    /// Finds all usages of the reference at point.
     pub fn find_all_refs(&self, position: FilePosition) -> Cancelable<Vec<(FileId, TextRange)>> {
         self.db.find_all_refs(position)
     }
+    /// Returns documentation string for a given target.
     pub fn doc_text_for(&self, nav: NavigationTarget) -> Cancelable<Option<String>> {
         self.db.doc_text_for(nav)
     }
+    /// Returns a `mod name;` declaration whihc created the current module.
     pub fn parent_module(&self, position: FilePosition) -> Cancelable<Vec<NavigationTarget>> {
         self.db.parent_module(position)
     }
+    /// Returns `::` separated path to the current module from the crate root.
     pub fn module_path(&self, position: FilePosition) -> Cancelable<Option<String>> {
         self.db.module_path(position)
     }
+    /// Returns crates this file belongs too.
     pub fn crate_for(&self, file_id: FileId) -> Cancelable<Vec<CrateId>> {
         self.db.crate_for(file_id)
     }
+    /// Returns the root file of the given crate.
     pub fn crate_root(&self, crate_id: CrateId) -> Cancelable<FileId> {
         Ok(self.db.crate_root(crate_id))
     }
+    /// Returns the set of possible targets to run for the current file.
     pub fn runnables(&self, file_id: FileId) -> Cancelable<Vec<Runnable>> {
         let file = self.db.source_file(file_id);
         Ok(runnables::runnables(self, &file, file_id))
     }
+    /// Computes syntax highlighting for the given file.
     pub fn highlight(&self, file_id: FileId) -> Cancelable<Vec<HighlightedRange>> {
         syntax_highlighting::highlight(&*self.db, file_id)
     }
+    /// Computes completions at the given position.
     pub fn completions(&self, position: FilePosition) -> Cancelable<Option<Vec<CompletionItem>>> {
         let completions = completion::completions(&self.db, position)?;
         Ok(completions.map(|it| it.into()))
     }
+    /// Computes assists (aks code actons aka intentions) for the given
+    /// position.
     pub fn assists(&self, frange: FileRange) -> Cancelable<Vec<SourceChange>> {
         Ok(self.db.assists(frange))
     }
+    /// Computes the set of diagnostics for the given file.
     pub fn diagnostics(&self, file_id: FileId) -> Cancelable<Vec<Diagnostic>> {
         self.db.diagnostics(file_id)
     }
+    /// Computes parameter information for the given call expression.
     pub fn resolve_callable(
         &self,
         position: FilePosition,
     ) -> Cancelable<Option<(FnSignatureInfo, Option<usize>)>> {
         self.db.resolve_callable(position)
     }
+    /// Computes the type of the expression at the given position.
     pub fn type_of(&self, frange: FileRange) -> Cancelable<Option<String>> {
         self.db.type_of(frange)
     }
+    /// Returns the edit required to rename reference at the position to the new
+    /// name.
     pub fn rename(
         &self,
         position: FilePosition,