Docs nitpicks

Author: Fuzzyzilla

src/axis.rs

@@ -1,3 +1,5 @@
+//! Axes descriptions of tool capabilities and limits.
+
 use crate::util::NicheF32;
 
 bitflags::bitflags! {
@@ -49,6 +51,7 @@ impl AvailableAxes {
     strum::IntoStaticStr,
     strum::EnumIter,
 )]
+/// An individual Tool axis.
 pub enum Axis {
     /// The tool can sense how much force is applied, purpendicular to the pad surface.
     Pressure,
@@ -60,7 +63,7 @@ pub enum Axis {
     Roll,
     /// The tool has a scroll wheel. It may report continuous motion as well as discrete steps.
     Wheel,
-    /// The tool has an absolute linear slider control, ranging from -1 to 1 with zero being the "natural" position.
+    /// The tool has an absolute linear slider control, `[-1, 1]` with zero being the "natural" position.
     Slider,
     /// The tool has a pressure-sensitive button, reporting how hard the user is pressing on it.
     ButtonPressure,
@@ -101,8 +104,9 @@ impl<U: Union + Clone> Union for Option<U> {
     }
 }
 
-/// Granularity of an axis. This does not affect the range of values.
-/// Describes the number of unique values between `0` and `1` of the associated unit.
+/// Describes the number of unique values in the entire range of the associated axis.
+///
+/// This does not affect the range of values nor the interpretation of values reported by a [`Pose`].
 #[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord)]
 #[repr(transparent)]
 pub struct Granularity(pub std::num::NonZeroU32);
@@ -125,12 +129,18 @@ impl Union for PositionGranularity {
     }
 }
 
-/// Limits of an axis's reported value.
+/// Limits of an axis's reported value. This does not affect the interpretation of a value reported by [`Pose`]
+///
+/// In many cases, you may ignore this value - this crate makes strong guarantees about the
+/// units values are reported in, and you may rely on those. However, this may desscribe e.g. that a tool only detects
+/// tilt in the +/-45° range.
 /// # Quirks
 /// This is a hint, and the value is not clamped - the hardware is allowed to report a value exceeding this in either direction.
 #[derive(Clone, Copy, Debug)]
 pub struct Limits {
+    /// Inclusive minimum
     pub min: f32,
+    /// Inclusive maximum
     pub max: f32,
 }
 impl From<Limits> for std::ops::RangeInclusive<f32> {
@@ -153,7 +163,7 @@ impl Union for Limits {
     }
 }
 
-/// Represents a normalized axis, always in the range `0..=1`
+/// Represents a normalized axis, always in the range `[0, 1]`
 /// Since the min and max are fixed, only the granularity is given, if known.
 #[derive(Clone, Copy, Debug, Default)]
 pub struct NormalizedInfo {
@@ -167,14 +177,14 @@ impl Union for NormalizedInfo {
     }
 }
 
+/// Info for an axis which may or may not correspond to a physical unit of length.
 #[derive(Clone, Copy, Debug)]
 pub enum LengthInfo {
-    /// The axis reports a `0..=1` range, where the value doesn't necessarily correlate linearly with a
+    /// The axis reports a `[0, 1]` range, where the value doesn't necessarily correlate linearly with a
     /// physical unit of distance.
-    /// In this case, [`Granularity`] is to be interpreted as the total number of states between 0 and 1.
     Normalized(NormalizedInfo),
     /// The axis reports a physical distance in centimeters, within the range provided by
-    /// [`Info::limits`]. In this case, [`Granularity`] is to be interpreted as "dots per cm".
+    /// [`Info::limits`].
     Centimeters(Info),
 }
 impl LengthInfo {
@@ -218,6 +228,7 @@ impl Default for LengthInfo {
     }
 }
 
+/// Generic information about an axis with hardware-defined limits.
 #[derive(Clone, Copy, Debug, Default)]
 pub struct Info {
     pub limits: Option<Limits>,
@@ -245,7 +256,7 @@ impl Union for PositionInfo {
     }
 }
 
-/// Information about a circular axis, always reporting in the range of `0..TAU`.
+/// Information about a circular axis, always reporting in the range of `[0, TAU)`.
 #[derive(Clone, Copy, Debug, Default)]
 pub struct CircularInfo {
     pub granularity: Option<Granularity>,
@@ -258,7 +269,7 @@ impl Union for CircularInfo {
     }
 }
 
-/// Information about a slider axis, always reporting in the range of `-1..=1` with zero being the resting point.
+/// Information about a slider axis, always reporting in the range of `[-1, 1]` with zero being the resting point.
 #[derive(Clone, Copy, Debug, Default)]
 pub struct SliderInfo {
     pub granularity: Option<Granularity>,
@@ -272,19 +283,15 @@ impl Union for SliderInfo {
 }
 
 /// A report of the limits and capabilities of all axes, or None if the axis is
-/// not supported by the device.
+/// not supported by the device. See [`Pose`] for descriptions.
 #[derive(Debug, Copy, Clone, Default)]
 pub struct FullInfo {
     /// The X and Y axes - always supported, and with units of logical pixels.
     pub position: [PositionInfo; 2],
-    /// A unitless normalized value in [-1, 1]
     pub slider: Option<SliderInfo>,
-    /// The rotation around the tool's long axis, always reported in radians `0..TAU` if available.
     pub roll: Option<CircularInfo>,
-    // Force axes. Ink *can* report these in grams, but for simplicities sake we normalize. Todo?
     pub pressure: Option<NormalizedInfo>,
     pub button_pressure: Option<NormalizedInfo>,
-    /// X/Y tilt, in radians from vertical. See [`Pose::tilt`].
     pub tilt: Option<Info>,
     pub wheel: Option<CircularInfo>,
     pub distance: Option<LengthInfo>,
@@ -312,6 +319,7 @@ impl Union for FullInfo {
 
 #[derive(thiserror::Error, Debug, Copy, Clone, PartialEq, Eq, Hash)]
 #[error("axis not supported")]
+/// An axis was queried that is not reported as available.
 pub struct UnsupportedAxisError;
 
 impl FullInfo {
@@ -441,7 +449,8 @@ pub struct Pose {
     ///
     /// This may have sub-pixel precision, and may exceed your window size in the negative or positive directions.
     pub position: [f32; 2],
-    /// Perpendicular distance from the surface of the tablet. See [`FullInfo::distance`] for interpretation.
+    /// Perpendicular distance from the surface of the tablet. This may be an arbitrary, unitless `[0, 1]` value, or
+    /// reported in physical centimeters, see the [`FullInfo::distance`] of the reporting [`Tool`](crate::tool::Tool) for interpretation.
     ///
     /// # Quirks
     /// This will not necessarily be zero when in contact with the device, and may
@@ -472,6 +481,6 @@ pub struct Pose {
     /// Absolute slider position, in `[-1, 1]`, where zero is the "natural" position.
     pub slider: NicheF32,
     /// The size of the contact ellipse. First element describes the X-axis width of the ellipse,
-    /// and second describes the Y-axis height. See [`FullInfo::contact_size`] for interpretation.
+    /// and second describes the Y-axis height. See [`FullInfo::contact_size`] of the reporting [`Tool`](crate::tool::Tool) for units.
     pub contact_size: Option<[f32; 2]>,
 }

src/events/mod.rs

@@ -28,7 +28,8 @@ impl std::ops::Sub for FrameTimestamp {
     }
 }
 
-/// Events associated with a specific `Tool`.
+/// Events associated with a specific [`Tool`].
+///
 /// Events other than Added and Removed are logically grouped into "Frames" representing grouping
 /// of events in time, providing the timestamp that the group's events occured at if available.
 /// Events within a frame are arbitrarily ordered and to be interpreted
@@ -87,7 +88,7 @@ pub enum ToolEvent<'a> {
     /// The tool has left sensing range or left the window region of the tablet.
     Out,
 }
-/// Events associated with a specific `Tablet`.
+/// Events associated with a specific [`Tablet`].
 #[derive(Clone, Copy, Debug)]
 pub enum TabletEvent {
     /// The tablet is new. May be enumerated at the start of the program,
@@ -96,7 +97,7 @@ pub enum TabletEvent {
     /// Unplugged or otherwise becomes unavailable. The tablet will be removed from the hardware report.
     Removed,
 }
-/// Events associated with a specific `Pad`.
+/// Events associated with a specific [`Pad`](pad::Pad).
 #[derive(Clone, Copy, Debug)]
 pub enum PadEvent<'a> {
     /// The pad is new. May be enumerated at the start of the program,
@@ -124,7 +125,7 @@ pub enum PadEvent<'a> {
     /// The pad has lost it's tablet association.
     Exit,
 }
-/// Events associated with a specific group within a larger Pad.
+/// Events associated with a specific [`Group`](pad::Group) within a larger [`Pad`](pad::Pad).
 #[derive(Clone, Copy, Debug)]
 pub enum PadGroupEvent<'a> {
     /// A ring was interacted.

src/lib.rs

@@ -67,6 +67,8 @@ enum Backing {
     Raw,
 }
 #[derive(Clone, Copy, Debug)]
+
+/// List of supported backends. This is not affected by enabled features.
 // Some are never constructed due to disabled features/target platform.
 #[allow(dead_code)]
 pub enum Backend {
@@ -89,7 +91,7 @@ pub enum PumpError {
     WaylandDispatch(#[from] wayland_client::DispatchError),
 }
 
-/// Manages a connection to the OS's tablet server. This is the main
+/// Maintains a connection to the OS's tablet server. This is the main
 /// entry point for enumerating hardware and listening for events.
 pub struct Manager {
     pub(crate) internal: platform::PlatformManager,
@@ -100,7 +102,9 @@ pub struct Manager {
     pub(crate) _backing: Backing,
 }
 impl Manager {
-    /// Dispatch pending events without blocking, updating hardware reports and returning an [`IntoIterator`] containing the events.
+    /// Dispatch pending events, updating hardware reports and returning an [`IntoIterator`] containing the events.
+    ///
+    /// This will not wait for new events, and will return immediately with empty events if there is nothing to do.
     #[allow(clippy::missing_errors_doc)]
     pub fn pump(&mut self) -> Result<Events<'_>, PumpError> {
         self.internal.pump()?;

src/pad.rs

@@ -34,17 +34,18 @@ pub mod group {
     /// The type of interactable being queried in a [`FeedbackFn`]
     #[derive(Copy, Clone)]
     pub enum FeedbackElement<'a> {
-        /// The [button](super::Pad::total_buttons) with the given pad index. This will only
+        /// The [button](super::Pad::total_buttons) index with the given pad. This will only
         /// be called with buttons [owned](Group::buttons) by the relevant group.
         Button(u32),
         Ring(&'a super::Ring),
         Strip(&'a super::Strip),
     }
 
     /// After the group switches to the given mode index, provide feedback to the OS as to the roles
-    /// of buttons, sliders, and rings within the group. Called potentially many times per switch.
+    /// of buttons, sliders, and rings within the group. Called potentially many times per mode switch.
     pub type FeedbackFn = dyn FnMut(&Group, u32, FeedbackElement<'_>) -> String;
 
+    /// A Pad reports one or more Groups. See the [pad module docs](crate::pad) for more info.
     pub struct Group {
         pub(crate) internal_id: crate::InternalID,
         /// How many mode layers does this group cycle through?
@@ -53,7 +54,9 @@ pub mod group {
         /// Sorted list of the pad button indices that are owned by this group.
         /// This is some subset of the [buttons reported by the Pad](super::Pad::total_buttons).
         pub buttons: Vec<u32>,
+        /// The set of rings belonging to this group.
         pub rings: Vec<super::Ring>,
+        /// The set of strips belonging to this strip.
         pub strips: Vec<super::Strip>,
         /// Called synchronously for each group element (buttons, rings, and strips) after a modeswitch on supporting platforms.
         /// Provides new description text for the roles of each element, which may be shown by on-screen displays or other means.

src/tool.rs

@@ -3,7 +3,7 @@
 //! Also called a *stylus* or *pointer*, these represent the device that the user holds to interact with a pad.
 //! "Tools" do not correspond with directly with the above concepts, for example a
 //! single stylus with a tip and eraser represents *two* tools, one for each end. These can be re-associated with
-//! each other through [`Tool::id`].
+//! each other through [`Tool::hardware_id`].
 //!
 //! See [`Type`] for more ideas of what a "tool" may represent.
 //!
@@ -41,6 +41,7 @@ impl std::fmt::Debug for ButtonID {
 #[repr(transparent)]
 pub struct HardwareID(pub(crate) u64);
 
+/// Describes the class of hardware a tool represents
 #[derive(Clone, Copy, Debug, strum::AsRefStr, PartialEq, Eq)]
 pub enum Type {
     Pen,