docing parser methods

crates/ra_syntax/src/parser_api.rs

@@ -61,7 +61,7 @@ pub(crate) fn start(&mut self) -> Marker {
         Marker::new(self.0.start())
     }
 
-    /// Advances the parser by one token.
+    /// Advances the parser by one token unconditionally.
     pub(crate) fn bump(&mut self) {
         self.0.bump();
     }
@@ -91,7 +91,7 @@ pub(crate) fn error<T: Into<String>>(&mut self, message: T) {
         self.0.error(message.into())
     }
 
-    /// Consume the next token if it is `kind`.
+    /// Consume the next token if `kind` matches.
     pub(crate) fn eat(&mut self, kind: SyntaxKind) -> bool {
         if !self.at(kind) {
             return false;

crates/ra_syntax/src/parser_impl.rs

@@ -22,10 +22,21 @@
 pub(crate) trait Sink {
     type Tree;
 
+    /// Adds new leaf to the current branch.
     fn leaf(&mut self, kind: SyntaxKind, text: SmolStr);
-    fn start_internal(&mut self, kind: SyntaxKind);
-    fn finish_internal(&mut self);
+
+    /// Start new branch and make it current.
+    fn start_branch(&mut self, kind: SyntaxKind);
+
+    /// Finish current branch and restore previous
+    /// branch as current.
+    fn finish_branch(&mut self);
+
     fn error(&mut self, error: SyntaxError);
+
+    /// Complete tree building. Make sure that
+    /// `start_branch` and `finish_branch` calls
+    /// are paired!
     fn finish(self) -> Self::Tree;
 }
 

crates/ra_syntax/src/parser_impl/event.rs

@@ -154,7 +154,7 @@ fn tombstone() -> Event {
                     self.finish(last);
                 }
                 Event::Token { kind, n_raw_tokens } => {
-                    self.eat_ws();
+                    self.eat_trivias();
                     let n_raw_tokens = n_raw_tokens as usize;
                     let len = self.tokens[self.token_pos..self.token_pos + n_raw_tokens]
                         .iter()
@@ -173,7 +173,7 @@ fn tombstone() -> Event {
 
     fn start(&mut self, kind: SyntaxKind) {
         if kind == SOURCE_FILE {
-            self.sink.start_internal(kind);
+            self.sink.start_branch(kind);
             return;
         }
         let n_trivias = self.tokens[self.token_pos..]
@@ -194,18 +194,18 @@ fn start(&mut self, kind: SyntaxKind) {
             n_attached_trivias(kind, leading_trivias)
         };
         self.eat_n_trivias(n_trivias - n_attached_trivias);
-        self.sink.start_internal(kind);
+        self.sink.start_branch(kind);
         self.eat_n_trivias(n_attached_trivias);
     }
 
     fn finish(&mut self, last: bool) {
         if last {
-            self.eat_ws()
+            self.eat_trivias()
         }
-        self.sink.finish_internal();
+        self.sink.finish_branch();
     }
 
-    fn eat_ws(&mut self) {
+    fn eat_trivias(&mut self) {
         while let Some(&token) = self.tokens.get(self.token_pos) {
             if !token.kind.is_trivia() {
                 break;

crates/ra_syntax/src/yellow/builder.rs

@@ -26,11 +26,11 @@ fn leaf(&mut self, kind: SyntaxKind, text: SmolStr) {
         self.inner.leaf(kind, text);
     }
 
-    fn start_internal(&mut self, kind: SyntaxKind) {
+    fn start_branch(&mut self, kind: SyntaxKind) {
         self.inner.start_internal(kind)
     }
 
-    fn finish_internal(&mut self) {
+    fn finish_branch(&mut self) {
         self.inner.finish_internal();
     }