renaming and doc comments

ghostcell/src/dlist_arena.rs

@@ -10,6 +10,7 @@ pub struct Node<'arena, 'id, T> {
 pub type NodeRef<'arena, 'id, T> = &'arena GhostCell<'id, Node<'arena, 'id, T>>;
 
 impl<'arena, 'id, T> Node<'arena, 'id, T> {
+    /// Create a new isolated node from T. Requires an arena.
     pub fn new(
         data: T,
         arena: &'arena TypedArena<Node<'arena, 'id, T>>
@@ -43,27 +44,29 @@ impl<'arena, 'id, T> Node<'arena, 'id, T> {
         }
     }
 
+    /// Insert `node2` right after `node1` in the list.
     pub fn insert_next(
-        node: NodeRef<'arena, 'id, T>,
-        next: NodeRef<'arena, 'id, T>,
+        node1: NodeRef<'arena, 'id, T>,
+        node2: NodeRef<'arena, 'id, T>,
         token: &mut GhostToken<'id>,
     ) {
-        // Step 1: unlink the prev and next pointers nodes adjacent to next.
-        Self::unlink(next, token);
+        // Step 1: unlink the prev and next pointers nodes adjacent to node2.
+        Self::unlink(node2, token);
 
-        // Step 2: link node.next pointer and node.next.prev pointer to next.
-        let old_node_next = node.borrow(token).next;
-        if let Some(node_next) = old_node_next {
-            node_next.borrow_mut(token).prev = Some(next);
+        // Step 2: link node1.next pointer and node1.next.prev pointer to node2.
+        let node1_old_next : Option<NodeRef<_>> = node1.borrow(token).next;
+        if let Some(node1_old_next) = node1_old_next {
+            node1_old_next.borrow_mut(token).prev = Some(node2);
         }
-        node.borrow_mut(token).next = Some(next);
+        node1.borrow_mut(token).next = Some(node2);
 
         // Step 3: link next to node and old_node_next (old node.next).
-        let next = next.borrow_mut(token);
-        next.prev = Some(node);
-        next.next = old_node_next;
+        let node2: &mut Node<_> = node2.borrow_mut(token);
+        node2.prev = Some(node1);
+        node2.next = node1_old_next;
     }
 
+    /// Remove the links of this node to and from its adjacent nodes.
     pub fn remove(node: NodeRef<'arena, 'id, T>, token: &mut GhostToken<'id>) {
         // Step 1: unlink the prev and next pointers nodes adjacent to node.
         Self::unlink(node, token);
@@ -99,6 +102,7 @@ impl<'arena, 'id, T> Node<'arena, 'id, T> {
         }
     }
 
+    /// Immutable interior iteration
     pub fn iterate(
         node: NodeRef<'arena, 'id, T>,
         token: &GhostToken<'id>,
@@ -106,7 +110,7 @@ impl<'arena, 'id, T> Node<'arena, 'id, T> {
     ) {
         let mut cur: Option<NodeRef<'arena, 'id, T>> = Some(node);
         while let Some(node) = cur {
-            let node = node.borrow(token); // immutably borrow `node` with `token`
+            let node : &Node<_> = node.borrow(token); // immutably borrow `node` with `token`
             f(&node.data);
             cur = node.next;
         }