From 1417f26f820bd6428b528c3dc6127fabb084115a Mon Sep 17 00:00:00 2001
From: Aleksey Kladov <aleksey.kladov@gmail.com>
Date: Sun, 28 Jan 2018 11:18:17 +0300
Subject: Document the design of `FileBuilder`

---
 src/tree/file_builder.rs | 16 +++++++++++-----
 src/tree/mod.rs          |  2 +-
 2 files changed, 12 insertions(+), 6 deletions(-)

(limited to 'src/tree')

diff --git a/src/tree/file_builder.rs b/src/tree/file_builder.rs
index 738705f02..47038496d 100644
--- a/src/tree/file_builder.rs
+++ b/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>,
diff --git a/src/tree/mod.rs b/src/tree/mod.rs
index aaf048c73..30a4b33a9 100644
--- a/src/tree/mod.rs
+++ b/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)]
-- 
cgit v1.2.3