Merge #15

15: Add minimal docs to most public symbols r=matklad a=CAD97

Also sticks a safety on some warnings that rustc provides.

If you're just stubbing out a module and don't want rustc refusing to compile it because you haven't documented it yet, stick `#![allow(missing_docs)]` at the top.

2 files changed, 26 insertions, 3 deletions

diff --git a/src/tree/file_builder.rs b/src/tree/file_builder.rs
index 939922cb2..738705f02 100644
--- a/src/tree/file_builder.rs
+++ b/src/tree/file_builder.rs
@@ -1,3 +1,6 @@
+// FIXME(CAD97): I don't understand this mod well enough to stub out docs for the public symbols yet
+#![allow(missing_docs)]
+
 use {SyntaxKind, TextRange, TextUnit};
 use super::{File, NodeData, NodeIdx, SyntaxErrorData};
 
@@ -8,6 +11,7 @@ pub trait Sink {
     fn error(&mut self) -> ErrorBuilder;
 }
 
+#[derive(Debug)]
 pub struct FileBuilder {
     text: String,
     nodes: Vec<NodeData>,
@@ -139,6 +143,7 @@ fn grow(left: &mut TextRange, right: TextRange) {
     *left = TextRange::from_to(left.start(), right.end())
 }
 
+#[derive(Debug)]
 pub struct ErrorBuilder<'f> {
     message: Option<String>,
     builder: &'f mut FileBuilder,
diff --git a/src/tree/mod.rs b/src/tree/mod.rs
index a330caf54..aaf048c73 100644
--- a/src/tree/mod.rs
+++ b/src/tree/mod.rs
@@ -7,6 +7,7 @@ use std::cmp;
 mod file_builder;
 pub 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)]
 pub struct SyntaxKind(pub(crate) u32);
 
@@ -37,12 +38,17 @@ pub(crate) struct SyntaxInfo {
     pub name: &'static str,
 }
 
+/// A token of Rust source.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub struct Token {
+    /// The kind of token.
     pub kind: SyntaxKind,
+    /// The length of the token.
     pub len: TextUnit,
 }
 
+/// The contents of a Rust source file.
+#[derive(Debug)]
 pub struct File {
     text: String,
     nodes: Vec<NodeData>,
@@ -50,6 +56,7 @@ pub struct File {
 }
 
 impl File {
+    /// The root node of this source file.
     pub fn root<'f>(&'f self) -> Node<'f> {
         assert!(!self.nodes.is_empty());
         Node {
@@ -59,6 +66,7 @@ impl File {
     }
 }
 
+/// A reference to a token in a Rust source file.
 #[derive(Clone, Copy)]
 pub struct Node<'f> {
     file: &'f File,
@@ -66,28 +74,34 @@ pub struct Node<'f> {
 }
 
 impl<'f> Node<'f> {
+    /// The kind of the token at this node.
     pub fn kind(&self) -> SyntaxKind {
         self.data().kind
     }
 
+    /// The text range covered by the token at this node.
     pub fn range(&self) -> TextRange {
         self.data().range
     }
 
+    /// The text at this node.
     pub fn text(&self) -> &'f str {
         &self.file.text.as_str()[self.range()]
     }
 
+    /// The parent node to this node.
     pub fn parent(&self) -> Option<Node<'f>> {
         self.as_node(self.data().parent)
     }
 
+    /// The children nodes of this node.
     pub fn children(&self) -> Children<'f> {
         Children {
             next: self.as_node(self.data().first_child),
         }
     }
 
+    /// Any errors contained in this node.
     pub fn errors(&self) -> SyntaxErrors<'f> {
         let pos = self.file.errors.iter().position(|e| e.node == self.idx);
         let next = pos.map(|i| ErrorIdx(i as u32)).map(|idx| SyntaxError {
@@ -123,7 +137,7 @@ impl<'f> cmp::PartialEq<Node<'f>> for Node<'f> {
 
 impl<'f> cmp::Eq for Node<'f> {}
 
-#[derive(Clone, Copy)]
+#[derive(Clone, Copy, Debug)]
 pub struct SyntaxError<'f> {
     file: &'f File,
     idx: ErrorIdx,
@@ -162,6 +176,7 @@ impl<'f> SyntaxError<'f> {
     }
 }
 
+#[derive(Debug)]
 pub struct Children<'f> {
     next: Option<Node<'f>>,
 }
@@ -176,6 +191,7 @@ impl<'f> Iterator for Children<'f> {
     }
 }
 
+#[derive(Debug)]
 pub struct SyntaxErrors<'f> {
     next: Option<SyntaxError<'f>>,
 }
@@ -190,9 +206,10 @@ impl<'f> Iterator for SyntaxErrors<'f> {
     }
 }
 
-#[derive(Clone, Copy, PartialEq, Eq)]
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
 struct NodeIdx(u32);
 
+#[derive(Debug)]
 struct NodeData {
     kind: SyntaxKind,
     range: TextRange,
@@ -215,9 +232,10 @@ impl ::std::ops::IndexMut<NodeIdx> for Vec<NodeData> {
     }
 }
 
-#[derive(Clone, Copy)]
+#[derive(Clone, Copy, Debug)]
 struct ErrorIdx(u32);
 
+#[derive(Debug)]
 struct SyntaxErrorData {
     node: NodeIdx,
     message: String,