Require documentation on reader public items.

lib/reader/src/error.rs

@@ -8,13 +8,16 @@ use std::result;
 /// The location of a `Token` or `Error`.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
 pub struct Location {
+    /// Line number, starting from 1.
     pub line_number: usize,
 }
 
 /// A parse error is returned when the parse failed.
 #[derive(Debug)]
 pub struct Error {
+    /// Location of the error.
     pub location: Location,
+    /// Error message.
     pub message: String,
 }
 
@@ -24,6 +27,7 @@ impl fmt::Display for Error {
     }
 }
 
+/// Result of a parser operation. The `Error` variant includes a location.
 pub type Result<T> = result::Result<T, Error>;
 
 // Create an `Err` variant of `Result<X>` from a location and `format!` args.

lib/reader/src/lib.rs

@@ -3,6 +3,8 @@
 //! The cton_reader library supports reading .cton files. This functionality is needed for testing
 //! Cretonne, but is not essential for a JIT compiler.
 
+#![deny(missing_docs)]
+
 extern crate cretonne;
 
 pub use error::{Location, Result, Error};

lib/reader/src/testcommand.rs

@@ -14,19 +14,27 @@
 
 use std::fmt::{self, Display, Formatter};
 
+/// A command appearing in a test file.
 #[derive(Clone, PartialEq, Eq, Debug)]
 pub struct TestCommand<'a> {
+    /// The command name as a string.
     pub command: &'a str,
+    /// The options following the command name.
     pub options: Vec<TestOption<'a>>,
 }
 
+/// An option on a test command.
 #[derive(Clone, PartialEq, Eq, Debug)]
 pub enum TestOption<'a> {
+    /// Single identifier flag: `foo`.
     Flag(&'a str),
+    /// A value assigned to an identifier: `foo=bar`.
     Value(&'a str, &'a str),
 }
 
 impl<'a> TestCommand<'a> {
+    /// Create a new TestCommand by parsing `s`.
+    /// The returned command contains references into `s`.
     pub fn new(s: &'a str) -> TestCommand<'a> {
         let mut parts = s.split_whitespace();
         let cmd = parts.next().unwrap_or("");
@@ -48,6 +56,8 @@ impl<'a> Display for TestCommand<'a> {
 }
 
 impl<'a> TestOption<'a> {
+    /// Create a new TestOption by parsing `s`.
+    /// The returned option contains references into `s`.
     pub fn new(s: &'a str) -> TestOption<'a> {
         match s.find('=') {
             None => TestOption::Flag(s),

lib/reader/src/testfile.rs

@@ -20,6 +20,7 @@ pub struct TestFile<'a> {
     pub commands: Vec<TestCommand<'a>>,
     /// `isa bar ...` lines.
     pub isa_spec: IsaSpec,
+    /// Parsed functions and additional details about each function.
     pub functions: Vec<(Function, Details<'a>)>,
 }
 
@@ -28,8 +29,12 @@ pub struct TestFile<'a> {
 /// The details to not affect the semantics of the function.
 #[derive(Debug)]
 pub struct Details<'a> {
+    /// Location of the `function` keyword that begins this function.
     pub location: Location,
+    /// Annotation comments that appeared inside or after the function.
     pub comments: Vec<Comment<'a>>,
+    /// Mapping of source entity numbers to parsed entity numbers.
+    /// Source locations of parsed entities.
     pub map: SourceMap,
 }