From 725a5d8f031ab6695484fa3b4ae824d3e40c6ede Mon Sep 17 00:00:00 2001
From: lifning <>
Date: Mon, 1 Nov 2021 21:14:25 -0700
Subject: [PATCH] more struct docs

---
 ferretro_components/src/provided/sdl2/canvas.rs |  2 +-
 ferretro_components/src/provided/sdl2/mod.rs    |  3 +++
 ferretro_components/src/provided/sdl2/opengl.rs |  2 +-
 ferretro_components/src/provided/stdlib.rs      | 17 +++++++++++++++++
 4 files changed, 22 insertions(+), 2 deletions(-)

diff --git a/ferretro_components/src/provided/sdl2/canvas.rs b/ferretro_components/src/provided/sdl2/canvas.rs
index 1a9311e..5e6c803 100644
--- a/ferretro_components/src/provided/sdl2/canvas.rs
+++ b/ferretro_components/src/provided/sdl2/canvas.rs
@@ -6,7 +6,7 @@ use sdl2::Sdl;
 use sdl2::rect::Rect;
 use sdl2::render::WindowCanvas;
 
-/// Creates a root window with SDL2, then displays each 2D video frame provided by the core
+/// Creates a root window in SDL2, then displays each 2D video frame provided by the core
 /// by converting it to a [sdl2::render::Texture] and copying it to the window's canvas.
 ///
 /// This component has no public interface and manages the SDL2 window on its own.
diff --git a/ferretro_components/src/provided/sdl2/mod.rs b/ferretro_components/src/provided/sdl2/mod.rs
index 62130be..dcf79fb 100644
--- a/ferretro_components/src/provided/sdl2/mod.rs
+++ b/ferretro_components/src/provided/sdl2/mod.rs
@@ -1,3 +1,6 @@
+//! [RetroComponent](crate::base::RetroComponent)s implementing interactive gameplay functionality
+//! with SDL2.
+
 mod canvas;
 mod audio;
 mod gamepad;
diff --git a/ferretro_components/src/provided/sdl2/opengl.rs b/ferretro_components/src/provided/sdl2/opengl.rs
index 0d919c4..99c3dbe 100644
--- a/ferretro_components/src/provided/sdl2/opengl.rs
+++ b/ferretro_components/src/provided/sdl2/opengl.rs
@@ -7,7 +7,7 @@ use sdl2::Sdl;
 use sdl2::rect::Rect;
 use sdl2::render::WindowCanvas;
 
-/// Uses SDL2 to create a root window with an OpenGL context and attaches libretro's
+/// Create a root window in SDL2 with an OpenGL context and attaches libretro's
 /// `hw_get_proc_address` calls to that of the [sdl2::VideoSubsystem].
 ///
 /// If the core provides 2D framebuffer data to the component, it will simply display it with a
diff --git a/ferretro_components/src/provided/stdlib.rs b/ferretro_components/src/provided/stdlib.rs
index dd8a0ac..a855d21 100644
--- a/ferretro_components/src/provided/stdlib.rs
+++ b/ferretro_components/src/provided/stdlib.rs
@@ -1,3 +1,6 @@
+//! Generally-useful [RetroComponent](crate::base::RetroComponent)s that have no dependencies
+//! outside of [std].
+
 use std::os::raw::c_uint;
 use std::path::PathBuf;
 use std::time::{Duration, Instant};
@@ -6,6 +9,7 @@ use crate::base::ControlFlow;
 use crate::prelude::*;
 use ferretro_base::retro::ffi::{Message, Language};
 
+/// Provides paths to the BIOS ROMs, core library, assets, and saves to cores that need them.
 #[derive(Default)]
 pub struct PathBufComponent {
     pub sys_path: Option<PathBuf>,
@@ -30,6 +34,9 @@ impl RetroCallbacks for PathBufComponent {
     }
 }
 
+/// Write's the core's own log statements to stderr.
+///
+/// The public member [Self::prefix] may be set to add a prefix to each logged line.
 #[derive(Default)]
 pub struct StderrLogComponent {
     pub prefix: String,
@@ -42,6 +49,10 @@ impl RetroCallbacks for StderrLogComponent {
     }
 }
 
+/// Writes all the input descriptors, variables, and subsystem information to stderr as they are
+/// provided by the core.
+///
+/// The public member [Self::prefix] may be set to add a prefix to each logged line.
 #[derive(Default)]
 pub struct StderrSysInfoLogComponent {
     pub prefix: String,
@@ -71,6 +82,9 @@ impl RetroCallbacks for StderrSysInfoLogComponent {
     }
 }
 
+/// Trace-logs every callback call made and their arguments to stderr.
+///
+/// The public member [Self::prefix] may be set to add a prefix to each logged line.
 #[derive(Default)]
 pub struct StderrCallTraceComponent {
     pub prefix: String,
@@ -199,6 +213,9 @@ impl RetroCallbacks for StderrCallTraceComponent {
     // TODO: etc...
 }
 
+/// Uses [std::thread::sleep] to maintain the target FPS specified by the core.
+///
+/// The sleep occurs during either `video_refresh` or at the end of `run()`.
 pub struct SleepFramerateLimitComponent {
     did_sleep: bool,
     fps: f64,