Document the design of `FileBuilder`

src/lib.rs

@@ -26,7 +26,8 @@ mod parser;
 #[allow(missing_docs)]
 pub mod syntax_kinds;
 pub use text::{TextRange, TextUnit};
-pub use tree::{File, FileBuilder, Node, Sink, SyntaxKind, Token};
+pub use tree::{File, Node, SyntaxKind, Token};
+pub(crate) use tree::{FileBuilder, Sink};
 pub use lexer::{next_token, tokenize};
 pub use parser::parse;
 

src/tree/file_builder.rs

@@ -1,10 +1,16 @@
-// FIXME(CAD97): I don't understand this mod well enough to stub out docs for the public symbols yet
-#![allow(missing_docs)]
-
+//! This module provides a way to construct a `File`.
+//! It is intended to be completely decoupled from the
+//! parser, so as to allow to evolve the tree representation
+//! and the parser algorithm independently.
+//!
+//! The `Sink` trait is the bridge between the parser and the
+//! tree builder: the parser produces a stream of events like
+//! `start node`, `finish node`, and `FileBuilder` converts
+//! this stream to a real tree.
 use {SyntaxKind, TextRange, TextUnit};
 use super::{File, NodeData, NodeIdx, SyntaxErrorData};
 
-pub trait Sink {
+pub(crate) trait Sink {
     fn leaf(&mut self, kind: SyntaxKind, len: TextUnit);
     fn start_internal(&mut self, kind: SyntaxKind);
     fn finish_internal(&mut self);
@@ -12,7 +18,7 @@ pub trait Sink {
 }
 
 #[derive(Debug)]
-pub struct FileBuilder {
+pub(crate) struct FileBuilder {
     text: String,
     nodes: Vec<NodeData>,
     errors: Vec<SyntaxErrorData>,

src/tree/mod.rs

@@ -5,7 +5,7 @@ use std::fmt;
 use std::cmp;
 
 mod file_builder;
-pub use self::file_builder::{FileBuilder, Sink};
+pub(crate) use self::file_builder::{FileBuilder, Sink};
 
 /// The kind of syntax node, e.g. `IDENT`, `USE_KW`, or `STRUCT_DEF`.
 #[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]