Add documentation

Justfile

@@ -1,12 +1,23 @@
 project := "serde_sjson"
 default := "run"
 
+build *ARGS:
+    cargo build {{ARGS}}
+    cargo readme > README.md
+
 run *ARGS:
     cargo run -- {{ARGS}}
 
 test *ARGS:
     cargo test {{ARGS}}
 
+doc:
+    cargo doc --no-deps
+    cargo readme > README.md
+
+serve-doc port='8000': doc
+    python3 -m http.server {{port}} --directory target/doc
+
 coverage *ARGS:
     RUSTFLAGS="-C instrument-coverage" cargo test --tests {{ARGS}} || true
     cargo profdata -- merge -sparse default*.profraw -o {{project}}.profdata

README.adoc

@@ -1,13 +0,0 @@
-= Serde SJSON
-:idprefix:
-:idseparator:
-:toc: macro
-:toclevels: 1
-:!toc-title:
-:caution-caption: :fire:
-:important-caption: :exclamtion:
-:note-caption: :paperclip:
-:tip-caption: :bulb:
-:warning-caption: :warning:
-
-A __ser__ialization/__de__serialization library for __Simplified JSON__, specifically, the Bitsquid/Stingray flavor.

README.md

@@ -0,0 +1,69 @@
+# serde_sjson
+
+A **ser**ialization/**de**serialization library for Simplified JSON,
+the Bitsquid/Stingray flavor of JSON.
+
+## Usage
+
+### Serializing
+
+```rust
+use serde::Serialize;
+use serde_sjson::Result;
+
+#[derive(Serialize)]
+struct Person {
+    name: String,
+    age: u8,
+    friends: Vec<String>,
+}
+
+fn main() -> Result<()> {
+    let data = Person {
+        name: String::from("Marc"),
+        age: 21,
+        friends: vec![String::from("Jessica"), String::from("Paul")],
+    };
+
+    let s = serde_sjson::to_string(&data)?;
+
+    println!("{}", s);
+
+    Ok(())
+}
+```
+
+### Deserializing
+
+```rust
+use serde::Deserialize;
+use serde_sjson::Result;
+
+#[derive(Deserialize)]
+struct Person {
+    name: String,
+    age: u8,
+    friends: Vec<String>,
+}
+
+fn main() -> Result<()> {
+    let sjson = r#"
+    name = Marc
+    age = 21
+    friends = [
+        Jessica
+        Paul
+    ]"#;
+
+    let data: Person = serde_sjson::from_str(sjson)?;
+
+    println!(
+        "{} is {} years old and has {} friends.",
+        data.name,
+        data.age,
+        data.friends.len()
+    );
+
+    Ok(())
+}
+```

README.tpl

@@ -0,0 +1,3 @@
+# {{crate}}
+
+{{readme}}

src/de.rs

@@ -5,6 +5,7 @@ use serde::Deserialize;
 use crate::error::{Error, ErrorCode, Result};
 use crate::parser::*;
 
+/// A container for deserializing Rust values from SJSON.
 pub struct Deserializer<'de> {
     input: Span<'de>,
     is_top_level: bool,
@@ -12,7 +13,7 @@ pub struct Deserializer<'de> {
 
 impl<'de> Deserializer<'de> {
     #![allow(clippy::should_implement_trait)]
-    pub fn from_str(input: &'de str) -> Self {
+    pub(crate) fn from_str(input: &'de str) -> Self {
         Self {
             input: Span::from(input),
             is_top_level: true,
@@ -65,6 +66,8 @@ impl<'de> Deserializer<'de> {
     }
 }
 
+/// Deserializes an SJSON string to a Rust value.
+#[inline]
 pub fn from_str<'a, T>(input: &'a str) -> Result<T>
 where
     T: Deserialize<'a>,

src/error.rs

@@ -2,8 +2,11 @@ use std::{fmt, io};
 
 use crate::parser::Token;
 
+/// An alias for a `Result` with `serde_sjson::Error`.
 pub type Result<T> = std::result::Result<T, Error>;
 
+/// A type encapsulating the different errors that might occurr
+/// during serialization or deserialization.
 #[derive(PartialEq)]
 pub struct Error {
     inner: Box<ErrorImpl>,

src/lib.rs

@@ -1,3 +1,71 @@
+//! A **ser**ialization/**de**serialization library for Simplified JSON,
+//! the Bitsquid/Stingray flavor of JSON.
+//!
+//! # Usage
+//!
+//! ## Serializing
+//!
+//! ```
+//! use serde::Serialize;
+//! use serde_sjson::Result;
+//!
+//! #[derive(Serialize)]
+//! struct Person {
+//!     name: String,
+//!     age: u8,
+//!     friends: Vec<String>,
+//! }
+//!
+//! fn main() -> Result<()> {
+//!     let data = Person {
+//!         name: String::from("Marc"),
+//!         age: 21,
+//!         friends: vec![String::from("Jessica"), String::from("Paul")],
+//!     };
+//!
+//!     let s = serde_sjson::to_string(&data)?;
+//!
+//!     println!("{}", s);
+//!
+//!     Ok(())
+//! }
+//! ```
+//!
+//! ## Deserializing
+//!
+//! ```
+//! use serde::Deserialize;
+//! use serde_sjson::Result;
+//!
+//! #[derive(Deserialize)]
+//! struct Person {
+//!     name: String,
+//!     age: u8,
+//!     friends: Vec<String>,
+//! }
+//!
+//! fn main() -> Result<()> {
+//!     let sjson = r#"
+//!     name = Marc
+//!     age = 21
+//!     friends = [
+//!         Jessica
+//!         Paul
+//!     ]"#;
+//!
+//!     let data: Person = serde_sjson::from_str(sjson)?;
+//!
+//!     println!(
+//!         "{} is {} years old and has {} friends.",
+//!         data.name,
+//!         data.age,
+//!         data.friends.len()
+//!     );
+//!
+//!     Ok(())
+//! }
+//! ```
+
 mod de;
 mod error;
 mod parser;

src/ser.rs

@@ -7,12 +7,14 @@ use crate::error::{Error, ErrorCode, Result};
 // TODO: Make configurable
 const INDENT: [u8; 2] = [0x20, 0x20];
 
+/// A container for serializing Rust values into SJSON.
 pub struct Serializer<W> {
     // The current indentation level
     level: usize,
     writer: W,
 }
 
+/// Serializes a value into a generic `io::Write`.
 #[inline]
 pub fn to_writer<T, W>(writer: &mut W, value: &T) -> Result<()>
 where
@@ -23,6 +25,7 @@ where
     value.serialize(&mut serializer)
 }
 
+/// Serializes a value into a byte vector.
 #[inline]
 pub fn to_vec<T>(value: &T) -> Result<Vec<u8>>
 where
@@ -33,6 +36,7 @@ where
     Ok(vec)
 }
 
+/// Serializes a value into a string.
 #[inline]
 pub fn to_string<T>(value: &T) -> Result<String>
 where
@@ -51,6 +55,7 @@ impl<W> Serializer<W>
 where
     W: io::Write,
 {
+    /// Creates a new `Serializer`.
     pub fn new(writer: W) -> Self {
         Self { level: 0, writer }
     }

tests/serialize.rs

@@ -1,4 +1,4 @@
-use serde_sjson::{to_string, Error};
+use serde_sjson::to_string;
 
 #[test]
 fn serialize_null() {