Start work on API docs for the language crate (#3981)

crates/language/src/syntax_map.rs

@@ -29,7 +29,7 @@ pub struct SyntaxMap {
 
 #[derive(Clone, Default)]
 pub struct SyntaxSnapshot {
-    layers: SumTree<SyntaxLayer>,
+    layers: SumTree<SyntaxLayerEntry>,
     parsed_version: clock::Global,
     interpolated_version: clock::Global,
     language_registry_version: usize,
@@ -84,7 +84,7 @@ struct SyntaxMapMatchesLayer<'a> {
 }
 
 #[derive(Clone)]
-struct SyntaxLayer {
+struct SyntaxLayerEntry {
     depth: usize,
     range: Range<Anchor>,
     content: SyntaxLayerContent,
@@ -117,17 +117,22 @@ impl SyntaxLayerContent {
     }
 }
 
+/// A layer of syntax highlighting, corresponding to a single syntax
+/// tree in a particular language.
 #[derive(Debug)]
-pub struct SyntaxLayerInfo<'a> {
-    pub depth: usize,
+pub struct SyntaxLayer<'a> {
+    /// The language for this layer.
     pub language: &'a Arc<Language>,
+    depth: usize,
     tree: &'a Tree,
     offset: (usize, tree_sitter::Point),
 }
 
+/// A layer of syntax highlighting. Like [SyntaxLayer], but holding
+/// owned data instead of references.
 #[derive(Clone)]
-pub struct OwnedSyntaxLayerInfo {
-    pub depth: usize,
+pub struct OwnedSyntaxLayer {
+    /// The language for this layer.
     pub language: Arc<Language>,
     tree: tree_sitter::Tree,
     offset: (usize, tree_sitter::Point),
@@ -691,7 +696,7 @@ impl SyntaxSnapshot {
             };
 
             layers.push(
-                SyntaxLayer {
+                SyntaxLayerEntry {
                     depth: step.depth,
                     range: step.range,
                     content,
@@ -741,7 +746,7 @@ impl SyntaxSnapshot {
         SyntaxMapCaptures::new(
             range.clone(),
             text,
-            [SyntaxLayerInfo {
+            [SyntaxLayer {
                 language,
                 tree,
                 depth: 0,
@@ -781,7 +786,7 @@ impl SyntaxSnapshot {
     }
 
     #[cfg(test)]
-    pub fn layers<'a>(&'a self, buffer: &'a BufferSnapshot) -> Vec<SyntaxLayerInfo> {
+    pub fn layers<'a>(&'a self, buffer: &'a BufferSnapshot) -> Vec<SyntaxLayer> {
         self.layers_for_range(0..buffer.len(), buffer).collect()
     }
 
@@ -789,7 +794,7 @@ impl SyntaxSnapshot {
         &'a self,
         range: Range<T>,
         buffer: &'a BufferSnapshot,
-    ) -> impl 'a + Iterator<Item = SyntaxLayerInfo> {
+    ) -> impl 'a + Iterator<Item = SyntaxLayer> {
         let start_offset = range.start.to_offset(buffer);
         let end_offset = range.end.to_offset(buffer);
         let start = buffer.anchor_before(start_offset);
@@ -813,7 +818,7 @@ impl SyntaxSnapshot {
                     let layer_start_offset = layer.range.start.to_offset(buffer);
                     let layer_start_point = layer.range.start.to_point(buffer).to_ts_point();
 
-                    info = Some(SyntaxLayerInfo {
+                    info = Some(SyntaxLayer {
                         tree,
                         language,
                         depth: layer.depth,
@@ -842,7 +847,7 @@ impl<'a> SyntaxMapCaptures<'a> {
     fn new(
         range: Range<usize>,
         text: &'a Rope,
-        layers: impl Iterator<Item = SyntaxLayerInfo<'a>>,
+        layers: impl Iterator<Item = SyntaxLayer<'a>>,
         query: fn(&Grammar) -> Option<&Query>,
     ) -> Self {
         let mut result = Self {
@@ -964,7 +969,7 @@ impl<'a> SyntaxMapMatches<'a> {
     fn new(
         range: Range<usize>,
         text: &'a Rope,
-        layers: impl Iterator<Item = SyntaxLayerInfo<'a>>,
+        layers: impl Iterator<Item = SyntaxLayer<'a>>,
         query: fn(&Grammar) -> Option<&Query>,
     ) -> Self {
         let mut result = Self::default();
@@ -1436,23 +1441,25 @@ fn insert_newlines_between_ranges(
     }
 }
 
-impl OwnedSyntaxLayerInfo {
+impl OwnedSyntaxLayer {
+    /// Returns the root syntax node for this layer.
     pub fn node(&self) -> Node {
         self.tree
             .root_node_with_offset(self.offset.0, self.offset.1)
     }
 }
 
-impl<'a> SyntaxLayerInfo<'a> {
-    pub fn to_owned(&self) -> OwnedSyntaxLayerInfo {
-        OwnedSyntaxLayerInfo {
+impl<'a> SyntaxLayer<'a> {
+    /// Returns an owned version of this layer.
+    pub fn to_owned(&self) -> OwnedSyntaxLayer {
+        OwnedSyntaxLayer {
             tree: self.tree.clone(),
             offset: self.offset,
-            depth: self.depth,
             language: self.language.clone(),
         }
     }
 
+    /// Returns the root node for this layer.
     pub fn node(&self) -> Node<'a> {
         self.tree
             .root_node_with_offset(self.offset.0, self.offset.1)
@@ -1564,7 +1571,7 @@ impl ChangeRegionSet {
         )
     }
 
-    fn intersects(&self, layer: &SyntaxLayer, text: &BufferSnapshot) -> bool {
+    fn intersects(&self, layer: &SyntaxLayerEntry, text: &BufferSnapshot) -> bool {
         for region in &self.0 {
             if region.depth < layer.depth {
                 continue;
@@ -1675,7 +1682,7 @@ impl<'a> SeekTarget<'a, SyntaxLayerSummary, SyntaxLayerSummary>
     }
 }
 
-impl sum_tree::Item for SyntaxLayer {
+impl sum_tree::Item for SyntaxLayerEntry {
     type Summary = SyntaxLayerSummary;
 
     fn summary(&self) -> Self::Summary {
@@ -1690,7 +1697,7 @@ impl sum_tree::Item for SyntaxLayer {
     }
 }
 
-impl std::fmt::Debug for SyntaxLayer {
+impl std::fmt::Debug for SyntaxLayerEntry {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         f.debug_struct("SyntaxLayer")
             .field("depth", &self.depth)