Some documentation fixes. (#97)

README.md

@@ -17,7 +17,7 @@ Rapidly prototype a simple 2D game, pixel-based animations, software renderers,
 
 ## Features
 
-- Built on modern graphics APIs powered by [`wgpu`](https://crates.io/crates/wgpu): DirectX 12, Vulkan, Metal, OpenGL.
+- Built on modern graphics APIs powered by [`wgpu`](https://crates.io/crates/wgpu): DirectX 12, Vulkan, Metal. OpenGL support is a work in progress.
 - Use your own custom shaders for special effects. (WIP)
 - Hardware accelerated scaling on perfect pixel boundaries.
 - Supports non-square pixel aspect ratios. (WIP)

src/lib.rs

@@ -237,12 +237,11 @@ impl Pixels {
         })
     }
 
-    /// Draw this pixel buffer to the configured [`SurfaceTexture`],
+    /// Draw this pixel buffer to the configured [`SurfaceTexture`] using a custom user-provided
-    /// using a custom user-provided render function.
+    /// render function.
     ///
-    /// Provides access to a [`wgpu::CommandEncoder`],
+    /// Provides access to a [`wgpu::CommandEncoder`], a [`wgpu::TextureView`] from the swapchain
-    /// a [`wgpu::TextureView`] from the swapchain which you can use to render to the screen,
+    /// which you can use to render to the screen, and the default [`ScalingRenderer`].
-    /// and the default [`ScalingRenderer`].
     ///
     /// # Errors
     ///
@@ -416,17 +415,19 @@ impl Pixels {
         )
     }
 
-    /// Provides access the the [`wgpu::Device`] `pixels` uses.
+    /// Provides access to the internal [`wgpu::Device`].
     pub fn device(&self) -> &wgpu::Device {
         &self.device
     }
 
-    /// Provides access the the [`wgpu::Queue`] `pixels` uses.
+    /// Provides access to the internal [`wgpu::Queue`].
     pub fn queue(&self) -> &wgpu::Queue {
         &self.queue
     }
 
-    /// Provides access the the [`wgpu::Texture`] `pixels` makes by uploading the frame you provide to the GPU.
+    /// Provides access to the internal source [`wgpu::Texture`].
+    ///
+    /// This is the pre-scaled texture copied from the pixel buffer.
     pub fn texture(&self) -> &wgpu::Texture {
         &self.texture
     }
@@ -446,7 +447,7 @@ impl<'req> PixelsBuilder<'req> {
     ///         power_preference: wgpu::PowerPreference::HighPerformance,
     ///         compatible_surface: None,
     ///     })
-    ///     .pixel_aspect_ratio(8.0 / 7.0)
+    ///     .enable_vsync(false)
     ///     .build()?;
     /// # Ok::<(), pixels::Error>(())
     /// ```
@@ -508,6 +509,11 @@ impl<'req> PixelsBuilder<'req> {
     /// # Panics
     ///
     /// The aspect ratio must be > 0.
+    ///
+    /// # Warning
+    ///
+    /// This documentation is hidden because support for pixel aspect ratio is incomplete.
+    #[doc(hidden)]
     pub fn pixel_aspect_ratio(mut self, pixel_aspect_ratio: f64) -> PixelsBuilder<'req> {
         assert!(pixel_aspect_ratio > 0.0);
 
@@ -521,7 +527,7 @@ impl<'req> PixelsBuilder<'req> {
     ///
     /// The `wgpu` present mode will be set to `Fifo` when Vsync is enabled, or `Immediate` when
     /// Vsync is disabled. To set the present mode to `Mailbox` or another value, use the
-    /// [`present_mode`] method.
+    /// [`PixelsBuilder::present_mode`] method.
     pub fn enable_vsync(mut self, enable_vsync: bool) -> PixelsBuilder<'req> {
         self.present_mode = if enable_vsync {
             wgpu::PresentMode::Fifo
@@ -533,7 +539,8 @@ impl<'req> PixelsBuilder<'req> {
 
     /// Set the `wgpu` present mode.
     ///
-    /// This differs from [`enable_vsync`] by allowing the present mode to be set to any value.
+    /// This differs from [`PixelsBuilder::enable_vsync`] by allowing the present mode to be set to
+    /// any value.
     pub fn present_mode(mut self, present_mode: wgpu::PresentMode) -> PixelsBuilder<'req> {
         self.present_mode = present_mode;
         self