Add doccomments to find functions in EngineState and StateWorkingSet (#14750)

# Description
Adds some doccomments to some of the methods in `engine_state.rs` and
`state_working_set.rs`. Also grouped together some of the `find` methods
in `engine_state.rs`, but didn't do so in `state_working_set.rs` since
they seem to already be grouped according to decl/overlay/module.

Follow-up to #14490. 

# User-Facing Changes
None

# Tests + Formatting
N/A

# After Submitting
N/A

crates/nu-protocol/src/engine/engine_state.rs

@@ -599,6 +599,9 @@ impl EngineState {
         }
     }
 
+    /// Find the [`DeclId`](nu_protocol::id::DeclId) corresponding to a declaration with `name`.
+    ///
+    /// Searches within active overlays, and filtering out overlays in `removed_overlays`.
     pub fn find_decl(&self, name: &[u8], removed_overlays: &[Vec<u8>]) -> Option<DeclId> {
         let mut visibility: Visibility = Visibility::new();
 
@@ -615,6 +618,9 @@ impl EngineState {
         None
     }
 
+    /// Find the name of the declaration corresponding to `decl_id`.
+    ///
+    /// Searches within active overlays, and filtering out overlays in `removed_overlays`.
     pub fn find_decl_name(&self, decl_id: DeclId, removed_overlays: &[Vec<u8>]) -> Option<&[u8]> {
         let mut visibility: Visibility = Visibility::new();
 
@@ -633,6 +639,33 @@ impl EngineState {
         None
     }
 
+    /// Find the [`OverlayId`](nu_protocol::id::OverlayId) corresponding to `name`.
+    ///
+    /// Searches all overlays, not just active overlays. To search only in active overlays, use [`find_active_overlay`](EngineState::find_active_overlay)
+    pub fn find_overlay(&self, name: &[u8]) -> Option<OverlayId> {
+        self.scope.find_overlay(name)
+    }
+
+    /// Find the [`OverlayId`](nu_protocol::id::OverlayId) of the active overlay corresponding to `name`.
+    ///
+    /// Searches only active overlays. To search in all overlays, use [`find_overlay`](EngineState::find_active_overlay)
+    pub fn find_active_overlay(&self, name: &[u8]) -> Option<OverlayId> {
+        self.scope.find_active_overlay(name)
+    }
+
+    /// Find the [`ModuleId`](nu_protocol::id::ModuleId) corresponding to `name`.
+    ///
+    /// Searches within active overlays, and filtering out overlays in `removed_overlays`.
+    pub fn find_module(&self, name: &[u8], removed_overlays: &[Vec<u8>]) -> Option<ModuleId> {
+        for overlay_frame in self.active_overlays(removed_overlays).rev() {
+            if let Some(module_id) = overlay_frame.modules.get(name) {
+                return Some(*module_id);
+            }
+        }
+
+        None
+    }
+
     pub fn get_module_comments(&self, module_id: ModuleId) -> Option<&[Span]> {
         self.doccomments.get_module_comments(module_id)
     }
@@ -654,16 +687,6 @@ impl EngineState {
         plugin_decls.into_iter().map(|(_, decl)| decl)
     }
 
-    pub fn find_module(&self, name: &[u8], removed_overlays: &[Vec<u8>]) -> Option<ModuleId> {
-        for overlay_frame in self.active_overlays(removed_overlays).rev() {
-            if let Some(module_id) = overlay_frame.modules.get(name) {
-                return Some(*module_id);
-            }
-        }
-
-        None
-    }
-
     pub fn which_module_has_decl(
         &self,
         decl_name: &[u8],
@@ -681,14 +704,6 @@ impl EngineState {
         None
     }
 
-    pub fn find_overlay(&self, name: &[u8]) -> Option<OverlayId> {
-        self.scope.find_overlay(name)
-    }
-
-    pub fn find_active_overlay(&self, name: &[u8]) -> Option<OverlayId> {
-        self.scope.find_active_overlay(name)
-    }
-
     pub fn find_commands_by_predicate(
         &self,
         mut predicate: impl FnMut(&[u8]) -> bool,

crates/nu-protocol/src/engine/state_working_set.rs

@@ -406,6 +406,7 @@ impl<'a> StateWorkingSet<'a> {
         self.delta.exit_scope();
     }
 
+    /// Find the [`DeclId`](nu_protocol::id::DeclId) corresponding to a predeclaration with `name`.
     pub fn find_predecl(&self, name: &[u8]) -> Option<DeclId> {
         let mut removed_overlays = vec![];
 
@@ -424,6 +425,10 @@ impl<'a> StateWorkingSet<'a> {
         None
     }
 
+    /// Find the [`DeclId`](nu_protocol::id::DeclId) corresponding to a declaration with `name`.
+    ///
+    /// Extends [`EngineState::find_decl`] to also search for predeclarations (if [`StateWorkingSet::search_predecls`] is set),
+    /// and declarations from scopes existing only in [`StateDelta`].
     pub fn find_decl(&self, name: &[u8]) -> Option<DeclId> {
         let mut removed_overlays = vec![];
 
@@ -462,6 +467,10 @@ impl<'a> StateWorkingSet<'a> {
         self.permanent_state.find_decl(name, &removed_overlays)
     }
 
+    /// Find the name of the declaration corresponding to `decl_id`.
+    ///
+    /// Extends [`EngineState::find_decl_name`] to also search for predeclarations (if [`StateWorkingSet::search_predecls`] is set),
+    /// and declarations from scopes existing only in [`StateDelta`].
     pub fn find_decl_name(&self, decl_id: DeclId) -> Option<&[u8]> {
         let mut removed_overlays = vec![];
 
@@ -503,6 +512,10 @@ impl<'a> StateWorkingSet<'a> {
             .find_decl_name(decl_id, &removed_overlays)
     }
 
+    /// Find the [`ModuleId`](nu_protocol::id::ModuleId) corresponding to `name`.
+    ///
+    /// Extends [`EngineState::find_module`] to also search for ,
+    /// and declarations from scopes existing only in [`StateDelta`].
     pub fn find_module(&self, name: &[u8]) -> Option<ModuleId> {
         let mut removed_overlays = vec![];
 
@@ -836,6 +849,7 @@ impl<'a> StateWorkingSet<'a> {
         self.permanent_state.has_overlay(name)
     }
 
+    /// Find the overlay corresponding to `name`.
     pub fn find_overlay(&self, name: &[u8]) -> Option<&OverlayFrame> {
         for scope_frame in self.delta.scope.iter().rev() {
             if let Some(overlay_id) = scope_frame.find_overlay(name) {