Add some function documentations (#5360)

helix-term/src/compositor.rs

@@ -1,4 +1,4 @@
-// Each component declares it's own size constraints and gets fitted based on it's parent.
+// Each component declares its own size constraints and gets fitted based on its parent.
 // Q: how does this work with popups?
 // cursive does compositor.screen_mut().add_layer_at(pos::absolute(x, y), <component>)
 use helix_core::Position;
@@ -97,6 +97,7 @@ pub fn resize(&mut self, area: Rect) {
         self.area = area;
     }
 
+    /// Add a layer to be rendered in front of all existing layers.
     pub fn push(&mut self, mut layer: Box<dyn Component>) {
         let size = self.size();
         // trigger required_size on init
@@ -136,7 +137,8 @@ pub fn handle_event(&mut self, event: &Event, cx: &mut Context) -> bool {
         let mut consumed = false;
 
         // propagate events through the layers until we either find a layer that consumes it or we
-        // run out of layers (event bubbling)
+        // run out of layers (event bubbling), starting at the front layer and then moving to the
+        // background.
         for layer in self.layers.iter_mut().rev() {
             match layer.handle_event(event, cx) {
                 EventResult::Consumed(Some(callback)) => {

helix-term/src/ui/popup.rs

@@ -42,6 +42,10 @@ pub fn new(id: &'static str, contents: T) -> Self {
         }
     }
 
+    /// Set the anchor position next to which the popup should be drawn.
+    ///
+    /// Note that this is not the position of the top-left corner of the rendered popup itself,
+    /// but rather the screen-space position of the information to which the popup refers.
     pub fn position(mut self, pos: Option<Position>) -> Self {
         self.position = pos;
         self
@@ -51,6 +55,10 @@ pub fn get_position(&self) -> Option<Position> {
         self.position
     }
 
+    /// Set the popup to prefer to render above or below the anchor position.
+    ///
+    /// This preference will be ignored if the viewport doesn't have enough space in the
+    /// chosen direction.
     pub fn position_bias(mut self, bias: Open) -> Self {
         self.position_bias = bias;
         self
@@ -78,6 +86,8 @@ pub fn ignore_escape_key(mut self, ignore: bool) -> Self {
         self
     }
 
+    /// Calculate the position where the popup should be rendered and return the coordinates of the
+    /// top left corner.
     pub fn get_rel_position(&mut self, viewport: Rect, cx: &Context) -> (u16, u16) {
         let position = self
             .position

helix-view/src/editor.rs

@@ -1341,6 +1341,8 @@ pub fn document_by_path_mut<P: AsRef<Path>>(&mut self, path: P) -> Option<&mut D
             .find(|doc| doc.path().map(|p| p == path.as_ref()).unwrap_or(false))
     }
 
+    /// Gets the primary cursor position in screen coordinates,
+    /// or `None` if the primary cursor is not visible on screen.
     pub fn cursor(&self) -> (Option<Position>, CursorKind) {
         let config = self.config();
         let (view, doc) = current_ref!(self);