Merge pull request #81 from sorairolake/add-docs

docs: Add missing documentation

Author: kennytm

src/lib.rs

@@ -28,6 +28,7 @@
 #![cfg_attr(not(feature = "std"), no_std)]
 #![cfg_attr(feature = "bench", feature(test))] // Unstable libraries
 #![cfg_attr(docsrs, feature(doc_auto_cfg))]
+#![warn(missing_docs)]
 #![warn(clippy::pedantic)]
 #![allow(
     clippy::must_use_candidate, // This is just annoying.

src/optimize.rs

@@ -252,6 +252,7 @@ mod parse_tests {
 //------------------------------------------------------------------------------
 //{{{ Optimizer
 
+/// QR code data optimizer.
 pub struct Optimizer<I> {
     parser: I,
     last_segment: Segment,
@@ -287,6 +288,7 @@ impl<I: Iterator<Item = Segment>> Optimizer<I> {
 }
 
 impl Parser<'_> {
+    /// Creates a new `Optimizer` based on this parser.
     pub fn optimize(self, version: Version) -> Optimizer<Self> {
         Optimizer::new(self, version)
     }

src/render/image.rs

@@ -1,3 +1,5 @@
+//! Raster image rendering support powered by the [`image`] crate.
+
 #![cfg(feature = "image")]
 
 use crate::render::{Canvas, Pixel};

src/render/mod.rs

@@ -34,7 +34,10 @@ pub trait Pixel: Copy + Sized {
 
 /// Rendering canvas of a QR code image.
 pub trait Canvas: Sized {
+    /// Type of an image pixel.
     type Pixel: Sized;
+
+    /// Type of the finalized image.
     type Image: Sized;
 
     /// Constructs a new canvas of the given dimensions.
@@ -43,6 +46,8 @@ pub trait Canvas: Sized {
     /// Draws a single dark pixel at the (x, y) coordinate.
     fn draw_dark_pixel(&mut self, x: u32, y: u32);
 
+    /// Draws a dark rectangle with dimensions `width`×`height` at the (`left`,
+    /// `top`) coordinate.
     fn draw_dark_rect(&mut self, left: u32, top: u32, width: u32, height: u32) {
         for y in top..(top + height) {
             for x in left..(left + width) {
@@ -121,6 +126,14 @@ impl<'a, P: Pixel> Renderer<'a, P> {
         self
     }
 
+    /// Sets the minimum total image width (and thus height) in pixels,
+    /// including the quiet zone if applicable. The renderer will try to find
+    /// the dimension as small as possible, such that each module in the QR code
+    /// has uniform size (no distortion).
+    ///
+    /// For instance, a version 1 QR code has 19 modules across including the
+    /// quiet zone. If we request an image of width ≥200px, we get that each
+    /// module's size should be 11px, so the actual image size will be 209px.
     #[deprecated(since = "0.4.0", note = "use `.min_dimensions(width, width)` instead")]
     pub fn min_width(&mut self, width: u32) -> &mut Self {
         self.min_dimensions(width, width)

src/render/string.rs

@@ -8,9 +8,15 @@ use alloc::string::String;
 use alloc::vec;
 use alloc::vec::Vec;
 
+/// Abstraction of an image element.
 pub trait Element: Copy {
+    /// Obtains the default element color when a module is dark or light.
     fn default_color(color: Color) -> Self;
+
+    /// Returns the number of bytes in `self`.
     fn strlen(self) -> usize;
+
+    /// Appends `self` to the end of the given `string`.
     fn append_to_string(self, string: &mut String);
 }
 

src/render/unicode.rs

@@ -8,9 +8,12 @@ use alloc::vec::Vec;
 
 const CODEPAGE: [&str; 4] = [" ", "\u{2584}", "\u{2580}", "\u{2588}"];
 
+/// An image pixel for UTF-8 rendering.
 #[derive(Copy, Clone, PartialEq, Eq)]
 pub enum Dense1x2 {
+    /// The pixel is dark colored.
     Dark,
+    /// The pixel is light colored.
     Light,
 }
 
@@ -37,6 +40,7 @@ impl Dense1x2 {
     }
 }
 
+/// A canvas for UTF-8 rendering with a resolution of 1×2 modules per character.
 pub struct Canvas1x2 {
     canvas: Vec<u8>,
     width: u32,

src/types.rs

@@ -1,3 +1,6 @@
+//! The `types` module contains types associated with the functional elements of
+//! a QR code.
+
 use crate::cast::As;
 use core::cmp::{Ordering, PartialOrd};
 use core::default::Default;