improve documentation

leops · leops · commit e6a92bf9dffb · 2023-01-09T16:56:06.000+01:00
diff --git a/crates/rome_parser/src/tree_sink.rs b/crates/rome_parser/src/tree_sink.rs
@@ -94,7 +94,7 @@ where
         }
     }
 
-    /// Reusing `NodeCache` between different [LosslessTreeSink]`s saves memory.
+    /// Reusing `NodeCache` between different [LosslessTreeSink]s saves memory.
     /// It allows to structurally share underlying trees.
     pub fn with_cache(text: &'a str, trivia: &'a [Trivia], cache: &'a mut NodeCache) -> Self {
         Self {
diff --git a/crates/rome_rowan/src/green/node_cache.rs b/crates/rome_rowan/src/green/node_cache.rs
@@ -42,6 +42,14 @@ impl<T: IntoRawPointer> GenerationalPointer<T> {
     }
 
     fn value(&self) -> &T::Pointee {
+        // SAFETY: This clears the least significant bit from `data`. This bit
+        // should have been set to zero in the original pointer due to the
+        // alignment requirements of the underlying data (this is checked by an
+        // assertion on debug builds), so this essentially extracts the pointer
+        // value from the bit field. Said point is safe to dereference at this
+        // point since we're holding a valid reference to `self` which
+        // guarantees `Drop` has not been called and the memory associated with
+        // the pointer has not been released yet.
         let data = self.data & !1;
         let ptr = data as *const T::Pointee;
         unsafe { &*ptr }
diff --git a/crates/rome_rowan/src/tree_builder.rs b/crates/rome_rowan/src/tree_builder.rs
@@ -36,7 +36,7 @@ impl<L: Language, S: SyntaxFactory<Kind = L::Kind>> TreeBuilder<'_, L, S> {
         TreeBuilder::default()
     }
 
-    /// Reusing `NodeCache` between different [TreeBuilder]`s saves memory.
+    /// Reusing `NodeCache` between different [TreeBuilder]s saves memory.
     /// It allows to structurally share underlying trees.
     pub fn with_cache(cache: &mut NodeCache) -> TreeBuilder<'_, L, S> {
         cache.increment_generation();

Original file line number	Diff line number	Diff line change
`@@ -94,7 +94,7 @@ where`
`94`	`94`	`}`
`95`	`95`	`}`
`96`	`96`
`97`		- /// Reusing `NodeCache` between different [LosslessTreeSink]`s saves memory.
	`97`	+ /// Reusing `NodeCache` between different [LosslessTreeSink]s saves memory.
`98`	`98`	`/// It allows to structurally share underlying trees.`
`99`	`99`	`pub fn with_cache(text: &'a str, trivia: &'a [Trivia], cache: &'a mut NodeCache) -> Self {`
`100`	`100`	`Self {`
Original file line number	Diff line number	Diff line change
`@@ -36,7 +36,7 @@ impl<L: Language, S: SyntaxFactory<Kind = L::Kind>> TreeBuilder<'_, L, S> {`
`36`	`36`	`TreeBuilder::default()`
`37`	`37`	`}`
`38`	`38`
`39`		- /// Reusing `NodeCache` between different [TreeBuilder]`s saves memory.
	`39`	+ /// Reusing `NodeCache` between different [TreeBuilder]s saves memory.
`40`	`40`	`/// It allows to structurally share underlying trees.`
`41`	`41`	`pub fn with_cache(cache: &mut NodeCache) -> TreeBuilder<'_, L, S> {`
`42`	`42`	`cache.increment_generation();`