Doc: add links

CHANGELOG.md

@@ -10,6 +10,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 
 ### Changed
 
+- Documentation: Add links to the underlying structs
+
 ### Removed
 
 ### Fixed

README.md

@@ -5,7 +5,7 @@
 [![docs.rs](https://img.shields.io/docsrs/leaprs?style=flat-square)](https://docs.rs/leaprs)
 ![Crates.io](https://img.shields.io/crates/l/leaprs?style=flat-square)
 
-LeapRS is a safe wrapper for LeapC, the [Leap Motion C
+LeapRS is an unofficial safe wrapper for LeapC, the [Leap Motion C
 API](https://docs.ultraleap.com/tracking-api/). It uses the generated binding
 provided by [leap-sys](https://crates.io/crates/leap-sys).
 
@@ -40,9 +40,9 @@ and distortion methods are not fully translated and not fully tested.
 
 The allocation API is not exposed.
 
-## Installation
+## Setup
 
-`cargo add leaprs`
+Add `leaprs` to the current project: `cargo add leaprs`
 
 You also need to install the [LeapMotion Tracking
 Software](https://developer.leapmotion.com/tracking-software-download).
@@ -54,25 +54,17 @@ environment variable `LEAPSDK_LIB_PATH` (default: `C:\Program
 Files\Ultraleap\LeapSDK\lib\x64` on Windows and
 `/usr/share/doc/ultraleap-hand-tracking-service` on Linux).
 
-### Using with previous SDK versions
-
-Disabling the `geminy` feature enables building application for the previous SDK
-generation (Orion). In Cargo.toml:
-
-```toml
-[dependencies = { version = "*", default-features = false }]
-```
-
-You also need to point the `LEAPSDK_LIB_PATH` to a SDK with the Orion version.
-
-## Runtime
-
 At runtime, the application requires the LeapC.dll file to be available. The
 easiest way to do it during development is to add its folder to the `PATH`
 environment variable. For distribution, refer to the SDK licensing.
 
 ## Quick start
 
+The main entrypoint is [Connection::create]. For most of the basic usage of hand
+tracking, you will have to use [Connection::poll] and retrieve the underlying
+event with [ConnectionMessage::event]. The various possible events are described
+in the [EventRef] enum, including [EventRef::Tracking] containing the hand positions.
+
 ```rust
 use leaprs::*;
 
@@ -88,6 +80,18 @@ for _ in 0..10 {
 }
 ```
 
+Most of the types in `leaprs` are wrappers with no data around the underlying `LeapC`
+structures. These wrappers expose both:
+
+- Handy methods for accessing the data, for example [TrackingEventRef::hands] lists
+  the visible hands
+- Direct access to the underlying data via the `Deref` trait, for example [HandRef]
+  gives direct access to [leap_sys::LEAP_HAND::confidence]: `hand_ref.confidence`
+
+When both members are available (`.hands` and `.hands()`), the function is the
+recommended one to get a safe wrapper. The field access can be useful to
+circumvent a `leaprs` limitation.
+
 ## `glam` and `nalgebra` Integration
 
 `leaprs` includes opt-in `glam` and `nalgebra` integrations.
@@ -145,6 +149,17 @@ for _ in 0..10 {
 }
 ```
 
+## Using with previous SDK versions
+
+Disabling the `geminy` feature enables building application for the previous SDK
+generation (Orion). In Cargo.toml:
+
+```toml
+[dependencies = { version = "*", default-features = false }]
+```
+
+You also need to point the `LEAPSDK_LIB_PATH` to a SDK with the Orion version.
+
 ## License
 
 Licensed under either of Apache License, Version 2.0 or MIT license at your option.

src/bone.rs

@@ -7,6 +7,8 @@ use crate::{LeapVectorRef, QuaternionRef};
 #[doc = ""]
 #[doc = " Bones are members of the LEAP_DIGIT struct."]
 #[doc = " @since 3.0.0"]
+/// # Fields
+/// Available via dereference: [LEAP_BONE]
 #[derive(Deref, Clone, Copy)]
 pub struct BoneRef<'a>(pub(crate) &'a LEAP_BONE);
 

src/clock_rebaser.rs

@@ -9,6 +9,8 @@ use crate::{leap_try, Error};
 #[doc = " \\ingroup Structs"]
 #[doc = " \\struct LEAP_CLOCK_REBASER"]
 #[doc = " An opaque clock rebase state structure. @since 3.1.2"]
+/// # Fields
+/// Available via dereference: [LEAP_CLOCK_REBASER].
 #[derive(Deref)]
 pub struct ClockRebaser(pub(crate) LEAP_CLOCK_REBASER);
 

src/connection_info.rs

@@ -10,6 +10,8 @@ use crate::ConnectionStatus;
 #[doc = " call LeapOpenConnection() to establish the connection; then call"]
 #[doc = " LeapGetConnectionInfo(), which creates this struct, to check the connection status."]
 #[doc = " @since 3.0.0"]
+/// # Fields
+/// Available via dereference: [LEAP_CONNECTION_INFO].
 #[derive(Deref, Clone, Copy)]
 pub struct ConnectionInfo(pub(crate) LEAP_CONNECTION_INFO);
 

src/connection_message.rs

@@ -8,6 +8,8 @@ use crate::event::EventRef;
 #[doc = " Defines a basic message from the LeapC message queue."]
 #[doc = " Set by calling LeapPollConnection()."]
 #[doc = " @since 3.0.0"]
+/// # Fields
+/// Available via dereference: [LEAP_CONNECTION_MESSAGE].
 #[derive(Deref, Clone, Copy)]
 pub struct ConnectionMessage<'a>(
     pub(crate) LEAP_CONNECTION_MESSAGE,

src/device_info.rs

@@ -8,6 +8,8 @@ use crate::{Capabilities, DevicePID, DeviceStatus};
 #[doc = " Get a LEAP_DEVICE_INFO by calling LeapGetDeviceInfo() with the handle for"]
 #[doc = " device. The device must be open."]
 #[doc = " @since 3.0.0"]
+/// # Fields
+/// Available via dereference: [LEAP_DEVICE_INFO].
 pub struct DeviceInfo {
     handle: LEAP_DEVICE_INFO,
     #[allow(dead_code)] // handle contains a pointer to serial

src/device_ref.rs

@@ -8,6 +8,8 @@ use crate::Device;
 #[doc = " Get a LEAP_DEVICE_REF by calling LeapGetDeviceList(). Access a device by"]
 #[doc = " calling LeapOpenDevice() with this reference. LeapOpenDevice() provides a"]
 #[doc = " LEAP_DEVICE struct, which is a handle to an open device."]
+/// # Fields
+/// Available via dereference: [LEAP_DEVICE_REF].
 #[derive(Deref, Clone, Copy)]
 pub struct DeviceRef(pub(crate) LEAP_DEVICE_REF);
 

src/digit.rs

@@ -6,6 +6,8 @@ use crate::BoneRef;
 #[doc = " Describes the digit of a hand."]
 #[doc = " Digits are members of the LEAP_HAND struct."]
 #[doc = " @since 3.0.0"]
+/// # Fields
+/// Available via dereference: [LEAP_DIGIT].
 #[derive(Deref, Clone, Copy)]
 pub struct DigitRef<'a>(pub(crate) &'a LEAP_DIGIT);
 

src/distortion_matrix.rs

@@ -11,6 +11,8 @@ use leap_sys::LEAP_DISTORTION_MATRIX;
 #[doc = ""]
 #[doc = " Current devices use a 64x64 point distortion grid."]
 #[doc = " @since 3.0.0"]
+/// # Fields
+/// Available via dereference: [LEAP_DISTORTION_MATRIX].
 #[derive(Deref, Clone, Copy)]
 pub struct DistortionMatrixRef<'a>(pub(crate) &'a LEAP_DISTORTION_MATRIX);
 

src/events/config_change_event.rs

@@ -9,5 +9,7 @@ use leap_sys::LEAP_CONFIG_CHANGE_EVENT;
 #[doc = " value to correlate the response to the originating request."]
 #[doc = " @returns The operation result code, a member of the eLeapRS enumeration."]
 #[doc = " @since 3.0.0"]
+/// # Fields
+/// Available via dereference: [LEAP_CONFIG_CHANGE_EVENT].
 #[derive(Deref, Clone, Copy)]
 pub struct ConfigChangeEventRef<'a>(pub(crate) &'a LEAP_CONFIG_CHANGE_EVENT);

src/events/config_response_event.rs

@@ -9,6 +9,8 @@ use crate::Variant;
 #[doc = " returns this event structure when the request has been processed. Use the requestID"]
 #[doc = " value to correlate the response to the originating request."]
 #[doc = " @since 3.0.0"]
+/// # Fields
+/// Available via dereference: [LEAP_CONFIG_RESPONSE_EVENT].
 #[derive(Deref, Clone, Copy)]
 pub struct ConfigResponseEventRef<'a>(pub(crate) &'a LEAP_CONFIG_RESPONSE_EVENT);
 

src/events/connection_event.rs

@@ -6,6 +6,8 @@ use crate::ServiceState;
 #[doc = "  \\ingroup Structs"]
 #[doc = " Received from LeapPollConnection() when a connection to the Ultraleap Tracking Service is established."]
 #[doc = " @since 3.0.0"]
+/// # Fields
+/// Available via dereference: [LEAP_CONNECTION_EVENT].
 #[derive(Deref, Clone, Copy)]
 pub struct ConnectionEventRef<'a>(pub(crate) &'a LEAP_CONNECTION_EVENT);
 

src/events/connection_lost_event.rs

@@ -8,6 +8,8 @@ use leap_sys::LEAP_CONNECTION_LOST_EVENT;
 #[doc = " this event. Otherwise, it can take up to 5 seconds of polling the connection to"]
 #[doc = " receive this event."]
 #[doc = " @since 3.0.0"]
+/// # Fields
+/// Available via dereference: [LEAP_CONNECTION_LOST_EVENT].
 #[derive(Deref, Clone, Copy)]
 pub struct ConnectionLostEventRef<'a>(pub(crate) &'a LEAP_CONNECTION_LOST_EVENT);
 

src/events/device_event.rs

@@ -9,6 +9,8 @@ use crate::{DeviceRef, DeviceStatus};
 #[doc = " device is detected. You can use the handle provided by the device filed to"]
 #[doc = " open a device so that you can access its properties."]
 #[doc = " @since 3.0.0"]
+/// # Fields
+/// Available via dereference: [LEAP_DEVICE_EVENT].
 #[derive(Deref, Clone, Copy)]
 pub struct DeviceEventRef<'a>(pub(crate) &'a LEAP_DEVICE_EVENT);
 

src/events/device_failure_event.rs

@@ -9,6 +9,8 @@ use crate::{Device, DeviceStatus};
 #[doc = " non-null, then you can use it to identify the failed device with a known,"]
 #[doc = " open device."]
 #[doc = " @since 3.0.0"]
+/// # Fields
+/// Available via dereference: [LEAP_DEVICE_FAILURE_EVENT].
 #[derive(Deref, Clone, Copy)]
 pub struct DeviceFailureEventRef<'a>(pub(crate) &'a LEAP_DEVICE_FAILURE_EVENT);
 

src/events/device_status_change_event.rs

@@ -6,6 +6,8 @@ use crate::{DeviceRef, DeviceStatus};
 #[doc = " A notification that a device's status has changed. One of these messages is received by the client"]
 #[doc = " as soon as the service is connected, or when a new device is attached."]
 #[doc = " @since 3.1.3"]
+/// # Fields
+/// Available via dereference: [LEAP_DEVICE_STATUS_CHANGE_EVENT].
 #[derive(Deref, Clone, Copy)]
 pub struct DeviceStatusChangeEventRef<'a>(pub(crate) &'a LEAP_DEVICE_STATUS_CHANGE_EVENT);
 

src/events/dropped_frame_event.rs

@@ -3,6 +3,8 @@ use leap_sys::LEAP_DROPPED_FRAME_EVENT;
 
 use crate::DroppedFrameType;
 
+/// # Fields
+/// Available via dereference: [LEAP_DROPPED_FRAME_EVENT].
 #[derive(Deref, Clone, Copy)]
 pub struct DroppedFrameEventRef<'a>(pub(crate) &'a LEAP_DROPPED_FRAME_EVENT);
 

src/events/eye_event.rs

@@ -3,6 +3,8 @@ use leap_sys::LEAP_EYE_EVENT;
 
 use crate::LeapVectorRef;
 
+/// # Fields
+/// Available via dereference: [LEAP_EYE_EVENT].
 #[derive(Deref, Clone, Copy)]
 pub struct EyeEventRef<'a>(pub(crate) &'a LEAP_EYE_EVENT);
 

src/events/head_pose_event.rs

@@ -3,6 +3,8 @@ use leap_sys::LEAP_HEAD_POSE_EVENT;
 
 use crate::{LeapVectorRef, QuaternionRef};
 
+/// # Fields
+/// Available via dereference: [LEAP_HEAD_POSE_EVENT].
 #[derive(Deref, Clone, Copy)]
 pub struct HeadPoseEventRef<'a>(pub(crate) &'a LEAP_HEAD_POSE_EVENT);
 

src/events/image_event.rs

@@ -9,6 +9,8 @@ use leap_sys::LEAP_IMAGE_EVENT;
 #[doc = " the buffer containing the image data -- which was allocated using the allocator"]
 #[doc = " function passed to LeapC using the LeapSetAllocator."]
 #[doc = " @since 4.0.0"]
+/// # Fields
+/// Available via dereference: [LEAP_IMAGE_EVENT].
 #[derive(Deref, Clone, Copy)]
 pub struct ImageEventRef<'a>(pub(crate) &'a LEAP_IMAGE_EVENT);
 

src/events/imu_event.rs

@@ -4,6 +4,8 @@ use leap_sys::LEAP_IMU_EVENT;
 use crate::{ImuFlag, LeapVectorRef};
 
 #[derive(Deref, Clone, Copy)]
+/// # Fields
+/// Available via dereference: [LEAP_IMU_EVENT].
 pub struct ImuEventRef<'a>(pub(crate) &'a LEAP_IMU_EVENT);
 
 impl<'a> ImuEventRef<'a> {

src/events/interpolation_tracking_event.rs

@@ -3,6 +3,8 @@ use std::ops::Deref;
 use crate::{sized_with_trailing_data::SizedWithTrailingData, FrameHeaderRef, HandRef};
 use leap_sys::LEAP_TRACKING_EVENT;
 
+/// # Fields
+/// Available via dereference: [LEAP_TRACKING_EVENT].
 pub struct InterpolationTrackingEvent(pub(crate) Box<SizedWithTrailingData<LEAP_TRACKING_EVENT>>);
 
 impl InterpolationTrackingEvent {

src/events/log_event.rs

@@ -6,6 +6,8 @@ use leap_sys::LEAP_LOG_EVENT;
 use crate::LogSeverity;
 
 #[doc = " A system log message. @since 3.0.0"]
+/// # Fields
+/// Available via dereference: [LEAP_LOG_EVENT].
 #[derive(Deref, Clone, Copy)]
 pub struct LogEventRef<'a>(pub(crate) &'a LEAP_LOG_EVENT);
 

src/events/log_events.rs

@@ -6,6 +6,8 @@ use crate::LogEventRef;
 #[doc = " A notification that a device's status has changed. One of these messages is received by the client"]
 #[doc = " as soon as the service is connected, or when a new device is attached."]
 #[doc = " @since 3.1.3"]
+/// # Fields
+/// Available via dereference: [LEAP_LOG_EVENTS].
 #[derive(Deref, Clone, Copy)]
 pub struct LogEventsRef<'a>(pub(crate) &'a LEAP_LOG_EVENTS);
 

src/events/point_mapping_change_event.rs

@@ -1,5 +1,7 @@
 use derive_deref::Deref;
 use leap_sys::LEAP_POINT_MAPPING_CHANGE_EVENT;
 
+/// # Fields
+/// Available via dereference: [LEAP_POINT_MAPPING_CHANGE_EVENT].
 #[derive(Deref, Clone, Copy)]
 pub struct PointMappingChangeEventRef<'a>(pub(crate) &'a LEAP_POINT_MAPPING_CHANGE_EVENT);

src/events/policy_event.rs

@@ -6,6 +6,8 @@ use crate::PolicyFlags;
 #[doc = " The response from a request to get or set a policy."]
 #[doc = " LeapPollConnection() creates this struct when the response becomes available."]
 #[doc = " @since 3.0.0"]
+/// # Fields
+/// Available via dereference: [LEAP_POLICY_EVENT].
 #[derive(Deref, Clone, Copy)]
 pub struct PolicyEventRef<'a>(pub(crate) &'a LEAP_POLICY_EVENT);
 

src/events/tracking_event.rs

@@ -6,6 +6,8 @@ use crate::{FrameHeaderRef, HandRef};
 #[doc = " A snapshot, or frame of data, containing the tracking data for a single moment in time."]
 #[doc = " The LEAP_FRAME struct is the container for all the tracking data."]
 #[doc = " @since 3.0.0"]
+/// # Fields
+/// Available via dereference: [LEAP_TRACKING_EVENT].
 #[derive(Deref, Clone, Copy)]
 pub struct TrackingEventRef<'a>(pub(crate) &'a LEAP_TRACKING_EVENT);
 

src/events/tracking_mode_event.rs

@@ -6,6 +6,8 @@ use crate::TrackingMode;
 #[doc = " The response from a request to get or set a policy."]
 #[doc = " LeapPollConnection() creates this struct when the response becomes available."]
 #[doc = " @since 3.0.0"]
+/// # Fields
+/// Available via dereference: [LEAP_TRACKING_MODE_EVENT].
 #[derive(Deref, Clone, Copy)]
 pub struct TrackingModeEventRef<'a>(pub(crate) &'a LEAP_TRACKING_MODE_EVENT);
 

src/frame_header.rs

@@ -2,5 +2,7 @@ use derive_deref::Deref;
 use leap_sys::LEAP_FRAME_HEADER;
 
 #[doc = " Identifying information for a frame of tracking data. @since 3.0.0"]
+/// # Fields
+/// Available via dereference: [LEAP_FRAME_HEADER].
 #[derive(Deref, Clone, Copy)]
 pub struct FrameHeaderRef<'a>(pub(crate) &'a LEAP_FRAME_HEADER);

src/hand.rs

@@ -16,6 +16,8 @@ pub enum HandType {
 
 #[doc = " Describes a tracked hand. @since 3.0.0"]
 #[derive(Deref, Clone, Copy)]
+/// # Fields
+/// Available via dereference: [LEAP_HAND].
 pub struct HandRef<'a>(pub(crate) &'a LEAP_HAND);
 
 impl<'a> HandRef<'a> {

src/image.rs

@@ -5,6 +5,8 @@ use crate::{DistortionMatrixRef, ImagePropertiesRef};
 
 #[doc = " An image associated with a frame of data."]
 #[doc = " @since 4.0.0"]
+/// # Fields
+/// Available via dereference: [LEAP_IMAGE].
 #[derive(Deref, Clone, Copy)]
 pub struct ImageRef<'a>(pub(crate) &'a LEAP_IMAGE);
 

src/image_properties.rs

@@ -4,6 +4,8 @@ use leap_sys::LEAP_IMAGE_PROPERTIES;
 use crate::{ImageFormat, ImageType};
 
 #[doc = " Properties of a sensor image."]
+/// # Fields
+/// Available via dereference: [LEAP_IMAGE_PROPERTIES].
 #[derive(Deref, Clone, Copy)]
 pub struct ImagePropertiesRef<'a>(pub(crate) &'a LEAP_IMAGE_PROPERTIES);
 

src/leap_vector.rs

@@ -2,8 +2,12 @@ use std::ops::Deref;
 
 use leap_sys::{_LEAP_VECTOR__bindgen_ty_1__bindgen_ty_1, LEAP_VECTOR};
 
+pub type LeapVectorFields = _LEAP_VECTOR__bindgen_ty_1__bindgen_ty_1;
+
 #[doc = " A three element, floating-point vector."]
 #[doc = " @since 3.0.0"]
+/// # Fields
+/// Available via dereference: [LeapVectorFields].
 pub struct LeapVectorRef<'a>(pub(crate) &'a LEAP_VECTOR);
 
 impl<'a> LeapVectorRef<'a> {
@@ -25,7 +29,7 @@ impl<'a> LeapVectorRef<'a> {
 }
 
 impl<'a> Deref for LeapVectorRef<'a> {
-    type Target = _LEAP_VECTOR__bindgen_ty_1__bindgen_ty_1;
+    type Target = LeapVectorFields;
 
     fn deref(&self) -> &Self::Target {
         unsafe { &self.0.__bindgen_anon_1.__bindgen_anon_1 }