From cd1a5e88ecee193296eedfb343f856b1a5655650 Mon Sep 17 00:00:00 2001
From: Kornel <kornel@geekhood.net>
Date: Mon, 25 Mar 2024 00:03:15 +0000
Subject: [PATCH] Document that threads are really needed

---
 src/collector.rs |  6 ++++++
 src/lib.rs       | 34 ++++++++++++++++++++++++++++++----
 2 files changed, 36 insertions(+), 4 deletions(-)

diff --git a/src/collector.rs b/src/collector.rs
index 17a8995..802f979 100644
--- a/src/collector.rs
+++ b/src/collector.rs
@@ -54,6 +54,8 @@ impl Collector {
     /// Presentation timestamp is time in seconds (since file start at 0) when this frame is to be displayed.
     ///
     /// If the first frame doesn't start at pts=0, the delay will be used for the last frame.
+    ///
+    /// If this function appears to be stuck after a few frames, it's because [`crate::Writer::write()`] is not running.
     #[cfg_attr(debug_assertions, track_caller)]
     pub fn add_frame_rgba(&self, frame_index: usize, frame: ImgVec<RGBA8>, presentation_timestamp: f64) -> GifResult<()> {
         debug_assert!(frame_index == 0 || presentation_timestamp > 0.);
@@ -74,6 +76,8 @@ impl Collector {
     /// Presentation timestamp is time in seconds (since file start at 0) when this frame is to be displayed.
     ///
     /// If the first frame doesn't start at pts=0, the delay will be used for the last frame.
+    ///
+    /// If this function appears to be stuck after a few frames, it's because [`crate::Writer::write()`] is not running.
     #[cfg(feature = "png")]
     #[inline]
     pub fn add_frame_png_data(&self, frame_index: usize, png_data: Vec<u8>, presentation_timestamp: f64) -> GifResult<()> {
@@ -93,6 +97,8 @@ impl Collector {
     /// Presentation timestamp is time in seconds (since file start at 0) when this frame is to be displayed.
     ///
     /// If the first frame doesn't start at pts=0, the delay will be used for the last frame.
+    ///
+    /// If this function appears to be stuck after a few frames, it's because [`crate::Writer::write()`] is not running.
     #[cfg(feature = "png")]
     pub fn add_frame_png_file(&self, frame_index: usize, path: PathBuf, presentation_timestamp: f64) -> GifResult<()> {
         self.queue.send(InputFrame {
diff --git a/src/lib.rs b/src/lib.rs
index bf60237..5feadca 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -15,6 +15,10 @@
  You should have received a copy of the GNU Affero General Public License
  along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */
+//! gif.ski library allows creation of GIF animations from [arbitrary pixels][ImgVec],
+//! or [PNG files][Collector::add_frame_png_file].
+//!
+//! See the [`new`] function to get started.
 #![doc(html_logo_url = "https://gif.ski/icon.png")]
 #![allow(clippy::bool_to_int_with_if)]
 #![allow(clippy::cast_possible_truncation)]
@@ -198,13 +202,35 @@ struct FrameMessage {
     screen_height: u16,
 }
 
-/// Start new encoding
+/// Start new encoding on two threads.
 ///
-/// Encoding is multi-threaded, and the `Collector` and `Writer`
-/// can be used on sepate threads.
+/// Encoding is always multi-threaded, and the `Collector` and `Writer`
+/// must be used on sepate threads.
 ///
 /// You feed input frames to the [`Collector`], and ask the [`Writer`] to
 /// start writing the GIF.
+///
+/// If you don't start writing, then adding frames will block forever.
+///
+///
+/// ```rust,no_run
+/// use gifski::*;
+///
+/// let (collector, writer) = gifski::new(Settings::default())?;
+/// std::thread::scope(|t| -> Result<(), Error> {
+///     let frames_thread = t.spawn(move || {
+///         for i in 0..10 {
+///             collector.add_frame_png_file(i, format!("frame{i:04}.png").into(), i as f64 * 0.1)?;
+///         }
+///         drop(collector);
+///         Ok(())
+///     });
+///
+///     writer.write(std::fs::File::create("demo.gif")?, &mut progress::NoProgress{})?;
+///     frames_thread.join().unwrap()
+/// })?;
+/// Ok::<_, Error>(())
+/// ```
 #[inline]
 pub fn new(settings: Settings) -> GifResult<(Collector, Writer)> {
     if settings.quality == 0 || settings.quality > 100 {
@@ -528,7 +554,7 @@ impl Writer {
         })
     }
 
-    /// Start writing frames. This function will not return until `Collector` is dropped.
+    /// Start writing frames. This function will not return until the [`Collector`] is dropped.
     ///
     /// `outfile` can be any writer, such as `File` or `&mut Vec`.
     ///