From b2ea22b25b060839ef1e5f9fef124dd4ed5b7107 Mon Sep 17 00:00:00 2001
From: Laurenz <laurmaedje@gmail.com>
Date: Tue, 19 Feb 2019 11:31:03 +0100
Subject: [PATCH] =?UTF-8?q?Vastly=20improve=20documentation=20=F0=9F=93=9D?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/doc.rs     |  2 +-
 src/lib.rs     | 18 ++++++++++++++++++
 src/parsing.rs | 14 +++++++-------
 src/pdf.rs     |  7 +++----
 4 files changed, 29 insertions(+), 12 deletions(-)

diff --git a/src/doc.rs b/src/doc.rs
index dcc4ae25e..a6d4b6891 100644
--- a/src/doc.rs
+++ b/src/doc.rs
@@ -8,7 +8,7 @@ use crate::parsing::{SyntaxTree, Node};
 
 /// Abstract representation of a complete typesetted document.
 ///
-/// This abstract thing can then be serialized into a specific format like PDF.
+/// This abstract thing can then be serialized into a specific format like _PDF_.
 #[derive(Debug, Clone, PartialEq)]
 pub struct Document {
     /// The pages of the document.
diff --git a/src/lib.rs b/src/lib.rs
index 924d75e42..b09a63359 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,6 +1,24 @@
 //! Typeset is a library for compiling documents written in the
 //! corresponding typesetting language into a typesetted document in an
 //! output format like _PDF_.
+//!
+//! # Example
+//! This is an example of compiling a _really_ simple document into _PDF_.
+//! ```
+//! use typeset::{parsing::{Tokenize, Parse}, doc::Generate, export::WritePdf};
+//!
+//! let path = "hello-typeset.pdf";
+//! # let path = "../target/hello-typeset.pdf";
+//! let mut file = std::fs::File::create(path).unwrap();
+//!
+//! // Tokenize, parse and then generate the document.
+//! let src = "Hello World from Typeset!";
+//! let doc = src.tokenize()
+//!     .parse().unwrap()
+//!     .generate().unwrap();
+//!
+//! file.write_pdf(&doc).unwrap();
+//! ```
 
 mod pdf;
 mod utility;
diff --git a/src/parsing.rs b/src/parsing.rs
index 1ed1ed9d5..173a5ba63 100644
--- a/src/parsing.rs
+++ b/src/parsing.rs
@@ -21,24 +21,24 @@ pub enum Token<'s> {
     /// A colon (`:`) indicating the beginning of function arguments.
     ///
     /// If a colon occurs outside of the function header, it will be
-    /// tokenized as a `Word`.
+    /// tokenized as a [Word](Token::Word).
     Colon,
-    /// Same as with `Colon`.
+    /// Same as with [Colon](Token::Colon).
     Equals,
     /// Two underscores, indicating text in _italics_.
     DoubleUnderscore,
     /// Two stars, indicating **bold** text.
     DoubleStar,
-    /// A dollar sign, indicating mathematical content.
+    /// A dollar sign, indicating _mathematical_ content.
     Dollar,
-    /// A hashtag starting a comment.
+    /// A hashtag starting a _comment_.
     Hashtag,
     /// Everything else just is a literal word.
     Word(&'s str),
 }
 
 
-/// A type that is seperable into logical units (tokens).
+/// A type that is separable into logical units (tokens).
 pub trait Tokenize {
     /// Tokenize self into logical units.
     fn tokenize<'s>(&'s self) -> Tokens<'s>;
@@ -297,7 +297,7 @@ pub struct Function<'s> {
 }
 
 
-/// A type that is parseable into a syntax tree.
+/// A type that is parsable into a syntax tree.
 pub trait Parse<'s> {
     /// Parse self into a syntax tree.
     fn parse(self) -> ParseResult<SyntaxTree<'s>>;
@@ -559,7 +559,7 @@ mod token_tests {
     }
 
     /// This test has a special look at the double underscore syntax, because
-    /// per Unicode standard they are not seperate words and thus harder to parse
+    /// per Unicode standard they are not separate words and thus harder to parse
     /// than the stars.
     #[test]
     fn tokenize_double_underscore() {
diff --git a/src/pdf.rs b/src/pdf.rs
index 4395cb7a2..c3a77c57d 100644
--- a/src/pdf.rs
+++ b/src/pdf.rs
@@ -7,8 +7,7 @@ use pdf::{PdfWriter, Id, Rect, Version, DocumentCatalog, PageTree,
 
 
 /// A type that is a sink for types that can be written conforming
-/// to the _PDF_ format (that may be things like sizes, other objects
-/// or whole documents).
+/// to the _PDF_ format.
 pub trait WritePdf<T> {
     /// Write self into a byte sink, returning how many bytes were written.
     fn write_pdf(&mut self, object: &T) -> io::Result<usize>;
@@ -44,7 +43,7 @@ impl<W: Write> WritePdf<Document> for W {
             parent: None,
             kids: (pages_start .. pages_end).collect(),
             data: PageData {
-                resources: Some(vec![Resource::Font(1, font_start)]),
+                resources: Some(vec![Resource::Font { nr: 1, id: font_start }]),
                 .. PageData::none()
             },
         })?;
@@ -81,7 +80,7 @@ impl<W: Write> WritePdf<Document> for W {
                 writer.write_obj(id, &Text::new()
                     .set_font(1, 13.0)
                     .move_pos(108.0, 734.0)
-                    .write_str(&string)
+                    .write_text(&string)
                     .to_stream()
                 )?;
                 id += 1;