add missing docs

Author: cmeissl

README.md

@@ -0,0 +1,18 @@
+# Pixman-rs
+
+This project contains rust bindings for [`pixman`](https://www.pixman.org/).
+
+From the official pixman docs:
+
+> Pixman is a low-level software library for pixel manipulation, providing features such as image compositing and trapezoid rasterization. 
+> Important users of pixman are the cairo graphics library and the X server.
+> 
+> Pixman is implemented as a library in the C programming language. It runs on many platforms, including Linux, BSD Derivatives, MacOS X, and Windows.
+> 
+> Pixman is free and open source software. It is available to be redistributed and/or modified under the terms of the MIT license. 
+
+## Currently unsupported features
+
+- Indexed image
+- Glyph cache
+- Separable convolution filter

pixman/src/color.rs

@@ -1,13 +1,14 @@
 use pixman_sys as ffi;
 
+/// Rgba color in the range of [`u16::MIN`] to [`u16::MAX`]
 #[derive(Debug, Clone, Copy)]
 #[repr(transparent)]
 pub struct Color(ffi::pixman_color_t);
 
 impl Color {
-    /// Create a [`Color`] from single components
+    /// Create a [`Color`] from the provided components
     ///
-    /// Note: Color component range from [`u16::MIN`] to [`u16::MAX`]
+    /// Note: Color component range of [`u16::MIN`] to [`u16::MAX`]
     #[inline]
     pub fn new(r: u16, g: u16, b: u16, a: u16) -> Self {
         Self(ffi::pixman_color_t {
@@ -18,11 +19,17 @@ impl Color {
         })
     }
 
+    /// Create a [`Color`] from the provided components
+    ///
+    /// Note: Color component range of `0f32` to `1f32`
     #[inline]
     pub fn from_f32(r: f32, g: f32, b: f32, a: f32) -> Self {
         Self::from_f64(r as f64, g as f64, b as f64, a as f64)
     }
 
+    /// Create a [`Color`] from the provided components
+    ///
+    /// Note: Color component range of `0f64` to `1f64`
     #[inline]
     pub fn from_f64(r: f64, g: f64, b: f64, a: f64) -> Self {
         Self(ffi::pixman_color_t {
@@ -33,6 +40,7 @@ impl Color {
         })
     }
 
+    /// Create a [`Color`] from the provided color value
     #[inline]
     pub fn from_u32(color8: u32) -> Self {
         let alpha = (color8 & 0xff000000) >> 24;
@@ -48,21 +56,25 @@ impl Color {
         Self::new(red as u16, green as u16, blue as u16, alpha as u16)
     }
 
+    /// Get the red color component
     #[inline]
     pub fn r(&self) -> u16 {
         self.0.red
     }
 
+    /// Get the green color component
     #[inline]
     pub fn g(&self) -> u16 {
         self.0.green
     }
 
+    /// Get the blue color component
     #[inline]
     pub fn b(&self) -> u16 {
         self.0.blue
     }
 
+    /// Get the alpha color component
     #[inline]
     pub fn a(&self) -> u16 {
         self.0.alpha

pixman/src/dither.rs

@@ -1,16 +1,24 @@
 use pixman_sys as ffi;
 use thiserror::Error;
 
+/// Defiens the possible dither operations
 #[derive(Debug, Clone, Copy)]
 pub enum Dither {
+    /// No dithering
     None,
+    /// Fast dithering
     Fast,
+    /// Good dithering
     Good,
+    /// Best dithering
     Best,
+    /// Ordered bayer 8 dithering
     OrderedBayer8,
+    /// Ordered blue noise 64
     OrderedBlueNoise64,
 }
 
+/// The dither operation is unknown
 #[derive(Debug, Error)]
 #[error("Unknown dither {0}")]
 pub struct UnknownDither(ffi::pixman_dither_t);

pixman/src/edge.rs

@@ -2,13 +2,15 @@ use std::{mem::MaybeUninit, os::raw::c_int};
 
 use crate::{ffi, Fixed, Line};
 
+/// Defines a single edge
 #[derive(Debug, Clone, Copy)]
 #[repr(transparent)]
 pub struct Edge(ffi::pixman_edge_t);
 
 impl Edge {
+    /// Create a edge from the provided values
     pub fn new(
-        bpp: isize,
+        bpp: i32,
         y_start: impl Into<Fixed>,
         x_top: impl Into<Fixed>,
         y_top: impl Into<Fixed>,
@@ -19,7 +21,7 @@ impl Edge {
         unsafe {
             ffi::pixman_edge_init(
                 edge.as_mut_ptr(),
-                bpp as c_int,
+                bpp,
                 y_start.into().into_raw(),
                 x_top.into().into_raw(),
                 y_top.into().into_raw(),
@@ -53,9 +55,10 @@ impl Edge {
         Self(unsafe { edge.assume_init() })
     }
 
-    pub fn step(&mut self, n: isize) {
+    /// Step an edge by any amount (including negative values)
+    pub fn step(&mut self, n: i32) {
         unsafe {
-            ffi::pixman_edge_step(&mut self.0, n as c_int);
+            ffi::pixman_edge_step(&mut self.0, n);
         }
     }
 

pixman/src/filter.rs

@@ -1,17 +1,26 @@
 use pixman_sys as ffi;
 use thiserror::Error;
 
+/// Defines the possible filter operations
 #[derive(Debug, Clone, Copy)]
 pub enum Filter {
+    /// Fast filtering
     Fast,
+    /// Good filtering
     Good,
+    /// Best filtering
     Best,
+    /// Nearest-neighbor filtering
     Nearest,
+    /// Bilinear filtering
     Bilinear,
+    /// Custom convolution kernel
     Convolution,
+    /// Custom separable convolution kernel
     SeparableConvolution,
 }
 
+/// The filter operation is unknown
 #[derive(Debug, Error)]
 #[error("Unknown filter {0}")]
 pub struct UnknownFilter(ffi::pixman_dither_t);

pixman/src/fixed.rs

@@ -1,36 +1,41 @@
 use pixman_sys as ffi;
 
+/// Fixed-point value
 #[derive(Debug, Clone, Copy)]
 #[repr(transparent)]
 pub struct Fixed(ffi::pixman_fixed_t);
 
 impl Fixed {
+    /// One
     pub const ONE: Fixed = Fixed::from_int(1);
+    /// Zero
     pub const ZERO: Fixed = Fixed::from_raw(0);
 
+    /// Initialize this fixed-point from a raw value
     #[inline]
     pub const fn from_raw(value: ffi::pixman_fixed_t) -> Self {
         Self(value)
     }
 
+    /// Initialize this fixed-point from an integer
     #[inline]
-    #[doc(alias = "pixman_int_to_fixed")]
     pub const fn from_int(value: i32) -> Self {
         Self(((value as u32) << 16) as ffi::pixman_fixed_t)
     }
 
+    /// Initialize this fixed-point from an `f64`
     #[inline]
-    #[doc(alias = "pixman_double_to_fixed")]
     pub fn from_double(value: f64) -> Self {
         Self((value * 65536.0) as ffi::pixman_fixed_t)
     }
 
+    /// Get the int value of this fixed point
     #[inline]
-    #[doc(alias = "pixman_fixed_to_int")]
     pub const fn to_int(self) -> i32 {
         self.0 >> 16
     }
 
+    /// Access the raw fixed-point value
     #[inline]
     pub fn into_raw(self) -> ffi::pixman_fixed_t {
         self.0

pixman/src/format.rs

@@ -2,60 +2,111 @@ use pixman_sys as ffi;
 #[cfg(feature = "drm-fourcc")]
 use thiserror::Error;
 
+/// Possible format codes
 #[derive(Debug, Clone, Copy)]
 pub enum FormatCode {
+    /// 128bpp RgbaFloat
     RgbaFloat,
+    /// 96bpp RgbFloat
     RgbFloat,
+    /// 32bpp A8R8G8B8
     A8R8G8B8,
+    /// 32bpp X8R8G8B8
     X8R8G8B8,
+    /// 32bpp A8B8G8R8
     A8B8G8R8,
+    /// 32bpp X8B8G8R8
     X8B8G8R8,
+    /// 32bpp B8G8R8A8
     B8G8R8A8,
+    /// 32bpp B8G8R8X8
     B8G8R8X8,
+    /// 32bpp R8G8B8A8
     R8G8B8A8,
+    /// 32bpp R8G8B8X8
     R8G8B8X8,
+    /// 32bpp X14R6G6B6
     X14R6G6B6,
+    /// 32bpp X2R10G10B10
     X2R10G10B10,
+    /// 32bpp A2R10G10B10
     A2R10G10B10,
+    /// 32bpp X2B10G10R10
     X2B10G10R10,
+    /// 32bpp A2B10G10R10
     A2B10G10R10,
+    /// sRGB A8R8G8B8sRGB
     A8R8G8B8sRGB,
+    /// 24bpp R8G8B8
     R8G8B8,
+    /// 24bpp B8G8R8
     B8G8R8,
+    /// 16bpp R5G6B5
     R5G6B5,
+    /// 16bpp B5G6R5
     B5G6R5,
+    /// 16bpp A1R5G5B5
     A1R5G5B5,
+    /// 16bpp X1R5G5B5
     X1R5G5B5,
+    /// 16bpp A1B5G5R5
     A1B5G5R5,
+    /// 16bpp X1B5G5R5
     X1B5G5R5,
+    /// 16bpp A4R4G4B4
     A4R4G4B4,
+    /// 16bpp X4R4G4B4
     X4R4G4B4,
+    /// 16bpp A4B4G4R4
     A4B4G4R4,
+    /// 16bpp X4B4G4R4
     X4B4G4R4,
+    /// 8bpp A8
     A8,
+    /// 8bpp R3G3B2
     R3G3B2,
+    /// 8bpp B2G3R3
     B2G3R3,
+    /// 8bpp A2R2G2B2
     A2R2G2B2,
+    /// 8bpp A2B2G2R2
     A2B2G2R2,
+    /// 8bpp C8
     C8,
+    /// 8bpp G8
     G8,
+    /// 8bpp X4A4
     X4A4,
+    /// 8bpp X4C4
     X4C4,
+    /// 8bpp X4G4
     X4G4,
+    /// 4bpp A4
     A4,
+    /// 4bpp R1G2B1
     R1G2B1,
+    /// 4bpp B1G2R1
     B1G2R1,
+    /// 4bpp A1R1G1B1
     A1R1G1B1,
+    /// 4bpp A1B1G1R1
     A1B1G1R1,
+    /// 4bpp C4
     C4,
+    /// 4bpp G4
     G4,
+    /// 1bpp A1
     A1,
+    /// 1bpp G1
     G1,
+    /// YUV YUY2
     YUY2,
+    /// YUV YV12
     YV12,
 }
 
 impl FormatCode {
+    /// Get the bpp for the specified format
     pub fn bpp(code: Self) -> u32 {
         let val = Into::<ffi::pixman_format_code_t>::into(code);
         let ofs = 24;
@@ -178,6 +229,7 @@ impl From<FormatCode> for ffi::pixman_format_code_t {
     }
 }
 
+/// The provided drm-fourcc has no matching format code
 #[cfg(feature = "drm-fourcc")]
 #[derive(Debug, Error)]
 #[error("Unsupported drm fourcc {0}")]
@@ -251,6 +303,7 @@ impl TryFrom<drm_fourcc::DrmFourcc> for FormatCode {
     }
 }
 
+/// The provided format code has no matching drm-fourcc
 #[cfg(feature = "drm-fourcc")]
 #[derive(Debug, Error)]
 #[error("Unsupported format code {0:?}")]

pixman/src/gradient_stop.rs

@@ -2,11 +2,13 @@ use pixman_sys as ffi;
 
 use crate::{Color, Fixed};
 
+/// Gradient-stop
 #[derive(Debug, Clone, Copy)]
 #[repr(transparent)]
 pub struct GradientStop(ffi::pixman_gradient_stop_t);
 
 impl GradientStop {
+    /// Initialize the gradient stop from the provided valued
     #[inline]
     pub fn new(x: impl Into<Fixed>, color: impl Into<Color>) -> Self {
         Self(ffi::pixman_gradient_stop {
@@ -15,11 +17,13 @@ impl GradientStop {
         })
     }
 
+    /// Access the stop x value
     #[inline]
     pub fn x(&self) -> Fixed {
         Fixed::from_raw(self.0.x)
     }
 
+    /// Access the stop color
     #[inline]
     pub fn color(&self) -> Color {
         Color::from(self.0.color)