From 5d483cb9980b6a74d02bd5d257b7d30e18955ef9 Mon Sep 17 00:00:00 2001 From: Aleksey Kladov Date: Wed, 2 Jan 2019 19:40:41 +0300 Subject: doctrings --- crates/ra_analysis/src/lib.rs | 90 +++++++++++++++++++++++++++++-------------- 1 file changed, 62 insertions(+), 28 deletions(-) (limited to 'crates/ra_analysis') 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 { 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 { 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 { 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 { 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 { 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 { 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 { 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> { - 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> { self.db.approximately_resolve_symbol(position) } + /// Finds all usages of the reference at point. pub fn find_all_refs(&self, position: FilePosition) -> Cancelable> { self.db.find_all_refs(position) } + /// Returns documentation string for a given target. pub fn doc_text_for(&self, nav: NavigationTarget) -> Cancelable> { self.db.doc_text_for(nav) } + /// Returns a `mod name;` declaration whihc created the current module. pub fn parent_module(&self, position: FilePosition) -> Cancelable> { self.db.parent_module(position) } + /// Returns `::` separated path to the current module from the crate root. pub fn module_path(&self, position: FilePosition) -> Cancelable> { self.db.module_path(position) } + /// Returns crates this file belongs too. pub fn crate_for(&self, file_id: FileId) -> Cancelable> { self.db.crate_for(file_id) } + /// Returns the root file of the given crate. pub fn crate_root(&self, crate_id: CrateId) -> Cancelable { 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> { 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> { syntax_highlighting::highlight(&*self.db, file_id) } + /// Computes completions at the given position. pub fn completions(&self, position: FilePosition) -> Cancelable>> { 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> { Ok(self.db.assists(frange)) } + /// Computes the set of diagnostics for the given file. pub fn diagnostics(&self, file_id: FileId) -> Cancelable> { self.db.diagnostics(file_id) } + /// Computes parameter information for the given call expression. pub fn resolve_callable( &self, position: FilePosition, ) -> Cancelable)>> { self.db.resolve_callable(position) } + /// Computes the type of the expression at the given position. pub fn type_of(&self, frange: FileRange) -> Cancelable> { 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, -- cgit v1.2.3