From 7324c807c526ee995955b9202ae377c17ae564e7 Mon Sep 17 00:00:00 2001
From: Kornel <kornel@cloudflare.com>
Date: Fri, 29 Nov 2024 20:14:51 +0000
Subject: [PATCH] API docs

---
 src/deflate/mod.rs | 2 +-
 src/filters.rs     | 1 +
 src/headers.rs     | 2 +-
 src/interlace.rs   | 3 +++
 src/options.rs     | 8 ++++++--
 5 files changed, 12 insertions(+), 4 deletions(-)

diff --git a/src/deflate/mod.rs b/src/deflate/mod.rs
index af2fca54..4a023975 100644
--- a/src/deflate/mod.rs
+++ b/src/deflate/mod.rs
@@ -11,8 +11,8 @@ mod zopfli_oxipng;
 #[cfg(feature = "zopfli")]
 pub use zopfli_oxipng::deflate as zopfli_deflate;
 
+/// DEFLATE algorithms supported by oxipng (for use in [`Options`][crate::Options])
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
-/// DEFLATE algorithms supported by oxipng
 pub enum Deflaters {
     /// Use libdeflater.
     Libdeflater {
diff --git a/src/filters.rs b/src/filters.rs
index c265e4ec..e1074ed5 100644
--- a/src/filters.rs
+++ b/src/filters.rs
@@ -2,6 +2,7 @@ use std::{fmt, fmt::Display, mem::transmute};
 
 use crate::error::PngError;
 
+/// Filtering strategy for use in [`Options`][crate::Options]
 #[repr(u8)]
 #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Clone, Copy, Hash)]
 pub enum RowFilter {
diff --git a/src/headers.rs b/src/headers.rs
index c85257ae..d869199a 100644
--- a/src/headers.rs
+++ b/src/headers.rs
@@ -71,8 +71,8 @@ pub struct Chunk {
     pub data: Vec<u8>,
 }
 
+/// [`Options`][crate::Options] to use when stripping chunks (metadata)
 #[derive(Debug, PartialEq, Eq, Clone)]
-/// Options to use when stripping chunks
 pub enum StripChunks {
     /// None
     None,
diff --git a/src/interlace.rs b/src/interlace.rs
index b4670cf5..07af3b1e 100644
--- a/src/interlace.rs
+++ b/src/interlace.rs
@@ -4,10 +4,13 @@ use bitvec::prelude::*;
 
 use crate::{headers::IhdrData, png::PngImage, PngError};
 
+/// Whether to enable progressive rendering. See [`Options`][crate::Options])
 #[repr(u8)]
 #[derive(Debug, PartialEq, Eq, Clone, Copy)]
 pub enum Interlacing {
+    /// Makes images load top to bottom.
     None,
+    /// Makes it possible to render partially-loaded images at lower resolution. Usually increases file sizes.
     Adam7,
 }
 
diff --git a/src/options.rs b/src/options.rs
index 69a99a93..152737b3 100644
--- a/src/options.rs
+++ b/src/options.rs
@@ -9,6 +9,8 @@ use log::warn;
 
 use crate::{deflate::Deflaters, filters::RowFilter, headers::StripChunks, interlace::Interlacing};
 
+/// Write destination for [`optimize`][crate::optimize].
+/// You can use [`optimize_from_memory`](crate::optimize_from_memory) to avoid external I/O.
 #[derive(Clone, Debug)]
 pub enum OutFile {
     /// Don't actually write any output, just calculate the best results.
@@ -46,7 +48,8 @@ impl OutFile {
     }
 }
 
-/// Where to read images from
+/// Where to read images from in [`optimize`][crate::optimize].
+/// You can use [`optimize_from_memory`](crate::optimize_from_memory) to avoid external I/O.
 #[derive(Clone, Debug)]
 pub enum InFile {
     Path(PathBuf),
@@ -133,7 +136,8 @@ pub struct Options {
     ///
     /// Default: `None`
     pub strip: StripChunks,
-    /// Which DEFLATE algorithm to use
+    /// Which DEFLATE (zlib) algorithm to use
+    #[cfg_attr(feature = "zopfli", doc = "(e.g. Zopfli)")]
     ///
     /// Default: `Libdeflater`
     pub deflate: Deflaters,