From 879432452d15d4e9c373a6233a0cd15e22f20ef3 Mon Sep 17 00:00:00 2001
From: Kirill Bulatov <mail4score@gmail.com>
Date: Sat, 20 Mar 2021 22:54:04 +0200
Subject: Docs

---
 crates/ide_db/src/helpers/import_assets.rs |  6 +++---
 crates/ide_db/src/items_locator.rs         | 20 +++++++++++++-------
 2 files changed, 16 insertions(+), 10 deletions(-)

(limited to 'crates/ide_db')

diff --git a/crates/ide_db/src/helpers/import_assets.rs b/crates/ide_db/src/helpers/import_assets.rs
index ae234eddc..6995c3e19 100644
--- a/crates/ide_db/src/helpers/import_assets.rs
+++ b/crates/ide_db/src/helpers/import_assets.rs
@@ -252,7 +252,7 @@ fn path_applicable_imports(
 
     match &path_candidate.qualifier {
         None => {
-            items_locator::locate_for_name(
+            items_locator::items_with_name(
                 sema,
                 current_crate,
                 path_candidate.name.clone(),
@@ -271,7 +271,7 @@ fn path_applicable_imports(
             let unresolved_qualifier =
                 path_to_string_stripping_turbo_fish(&first_segment_unresolved.full_qualifier);
             let unresolved_first_segment = first_segment_unresolved.fist_segment.text();
-            items_locator::locate_for_name(
+            items_locator::items_with_name(
                 sema,
                 current_crate,
                 path_candidate.name.clone(),
@@ -416,7 +416,7 @@ fn trait_applicable_items(
     let db = sema.db;
 
     let mut required_assoc_items = FxHashSet::default();
-    let trait_candidates = items_locator::locate_for_name(
+    let trait_candidates = items_locator::items_with_name(
         sema,
         current_crate,
         trait_candidate.assoc_item_name.clone(),
diff --git a/crates/ide_db/src/items_locator.rs b/crates/ide_db/src/items_locator.rs
index 088be72c4..518cddd74 100644
--- a/crates/ide_db/src/items_locator.rs
+++ b/crates/ide_db/src/items_locator.rs
@@ -1,6 +1,7 @@
-//! This module contains an import search functionality that is provided to the assists module.
-//! Later, this should be moved away to a separate crate that is accessible from the assists module.
-
+//! This module has the functionality to search the project and its dependencies for a certain item,
+//! by its name and a few criteria.
+//! The main reason for this module to exist is the fact that project's items and dependencies' items
+//! are located in different caches, with different APIs.
 use either::Either;
 use hir::{
     import_map::{self, ImportKind},
@@ -16,24 +17,29 @@ use crate::{
 };
 use rustc_hash::FxHashSet;
 
-pub(crate) const DEFAULT_QUERY_SEARCH_LIMIT: usize = 40;
+/// A value to use, when uncertain which limit to pick.
+pub const DEFAULT_QUERY_SEARCH_LIMIT: usize = 40;
 
-/// TODO kb docs here and around + update the module doc
+/// Three possible ways to search for the name in associated and/or other items.
 #[derive(Debug, Clone, Copy)]
 pub enum AssocItemSearch {
+    /// Search for the name in both associated and other items.
     Include,
+    /// Search for the name in other items only.
     Exclude,
+    /// Search for the name in the associated items only.
     AssocItemsOnly,
 }
 
-pub fn locate_for_name(
+/// Searches for importable items with the given name in the crate and its dependencies.
+pub fn items_with_name(
     sema: &Semantics<'_, RootDatabase>,
     krate: Crate,
     name: NameToImport,
     assoc_item_search: AssocItemSearch,
     limit: Option<usize>,
 ) -> FxHashSet<ItemInNs> {
-    let _p = profile::span("locate_for_name").detail(|| {
+    let _p = profile::span("items_with_name").detail(|| {
         format!(
             "Name: {} ({:?}), crate: {:?}, limit: {:?}",
             name.text(),
-- 
cgit v1.2.3