diff --git a/crates/ra_analysis/src/completion.rs b/crates/ra_analysis/src/completion.rs
index 739ca6ae83..ce777a771e 100644
--- a/crates/ra_analysis/src/completion.rs
+++ b/crates/ra_analysis/src/completion.rs
@@ -28,7 +28,21 @@ pub use crate::completion::completion_item::{CompletionItem, InsertText, Complet
 /// incomplete and can look really weird.
 ///
 /// Once the context is collected, we run a series of completion routines which
-/// look at the context and produce completion items.
+/// look at the context and produce completion items. One subtelty about this
+/// phase is that completion engine should not filter by the substring which is
+/// already present, it should give all possible variants for the identifier at
+/// the caret. In other words, for
+///
+/// ```no-run
+/// fn f() {
+///     let foo = 92;
+///     let _ = bar<|>
+/// }
+/// ```
+///
+/// `foo` *should* be present among the completion variants. Filtering by
+/// identifier prefix/fuzzy match should be done higher in the stack, together
+/// with ordering of completions (currently this is done by the client).
 pub(crate) fn completions(
     db: &db::RootDatabase,
     position: FilePosition,