Improve the examples

simconnect-sdk/Cargo.toml

@@ -18,3 +18,10 @@ num_enum = "0.5"
 tracing = "0.1"
 thiserror = "1.0"
 simconnect-sdk-derive = { path = "../simconnect-sdk-derive", optional = true }
+
+# docs.rs-specific configuration
+[package.metadata.docs.rs]
+# document all features
+all-features = true
+# defines the configuration attribute `docsrs`
+rustdoc-args = ["--cfg", "docsrs"]

simconnect-sdk/src/lib.rs

@@ -1,7 +1,63 @@
 //! # SimConnect SDK
 //! SimConnect SDK in Rust.
 //!
-//! See [examples](https://github.com/mihai-dinculescu/simconnect-sdk/tree/main/examples/src).
+//! ## Usage
+
+//! ```toml
+//! [dependencies]
+//! simconnect-sdk = { version = "0.1", features = ["derive"] }
+//! ```
+//!
+//! ```no_run
+//! use simconnect_sdk::{Notification, SimConnect, SimConnectObject};
+//!
+//! /// A data structure that will be used to receive data from SimConnect.
+//! #[derive(Debug, Clone, SimConnectObject)]
+//! #[simconnect(period = "second")]
+//! struct GpsData {
+//!     #[simconnect(name = "PLANE LATITUDE", unit = "degrees")]
+//!     lat: f64,
+//!     #[simconnect(name = "PLANE LONGITUDE", unit = "degrees")]
+//!     lon: f64,
+//!     #[simconnect(name = "PLANE LONGITUDE", unit = "degrees")]
+//!     alt: f64,
+//! }
+//!
+//! fn main() -> Result<(), Box<dyn std::error::Error>> {
+//!     let client = SimConnect::new("Simple Program");
+//!
+//!     match client {
+//!         Ok(mut client) => loop {
+//!             let notification = client.get_next_dispatch()?;
+//!
+//!             match notification {
+//!                 Some(Notification::Open) => {
+//!                     println!("Open");
+//!
+//!                     // The struct must be registered after the connection is successfully open
+//!                     client.register_object::<GpsData>()?;
+//!                 }
+//!                 Some(Notification::Data(data)) => {
+//!                     if let Ok(gps_data) = GpsData::try_from(&data) {
+//!                         println!("GPS Data: {gps_data:?}");
+//!                     }
+//!                 }
+//!                 _ => (),
+//!             }
+//!
+//!             // sleep for about a frame to reduce CPU usage
+//!             std::thread::sleep(std::time::Duration::from_millis(16));
+//!         },
+//!         Err(e) => {
+//!             println!("Error: {e:?}")
+//!         }
+//!     }
+//!
+//!     Ok(())
+//! }
+//! ```
+//!
+//! See [more examples](https://github.com/mihai-dinculescu/simconnect-sdk/tree/main/examples).
 
 mod bindings;
 mod domain;
@@ -19,6 +75,8 @@ pub use simconnect::SimConnect;
 pub use simconnect_object_ext::SimConnectObjectExt;
 
 #[cfg(feature = "simconnect-sdk-derive")]
+#[cfg_attr(docsrs, doc(cfg(feature = "simconnect-sdk-derive")))]
 extern crate simconnect_sdk_derive;
 #[cfg(feature = "simconnect-sdk-derive")]
+#[cfg_attr(docsrs, doc(cfg(feature = "simconnect-sdk-derive")))]
 pub use simconnect_sdk_derive::*;

simconnect-sdk/src/simconnect.rs

@@ -7,13 +7,65 @@ use crate::{
 };
 
 /// SimConnect SDK Client.
+///
+/// # Example
+///
+/// ```no_run
+/// use simconnect_sdk::{Notification, SimConnect, SimConnectObject};
+///
+/// /// A data structure that will be used to receive data from SimConnect.
+/// #[derive(Debug, Clone, SimConnectObject)]
+/// #[simconnect(period = "second")]
+/// struct GpsData {
+///     #[simconnect(name = "PLANE LATITUDE", unit = "degrees")]
+///     lat: f64,
+///     #[simconnect(name = "PLANE LONGITUDE", unit = "degrees")]
+///     lon: f64,
+///     #[simconnect(name = "PLANE LONGITUDE", unit = "degrees")]
+///     alt: f64,
+/// }
+///
+/// fn main() -> Result<(), Box<dyn std::error::Error>> {
+///     let client = SimConnect::new("Simple Program");
+///
+///     match client {
+///         Ok(mut client) => loop {
+///             let notification = client.get_next_dispatch()?;
+///
+///             match notification {
+///                 Some(Notification::Open) => {
+///                     println!("Open");
+///
+///                     // The struct must be registered after the connection is successfully open
+///                     client.register_object::<GpsData>()?;
+///                 }
+///                 Some(Notification::Data(data)) => {
+///                     if let Ok(gps_data) = GpsData::try_from(&data) {
+///                         println!("GPS Data: {gps_data:?}");
+///                     }
+///                 }
+///                 _ => (),
+///             }
+///
+///             // sleep for about a frame to reduce CPU usage
+///             std::thread::sleep(std::time::Duration::from_millis(16));
+///         },
+///         Err(e) => {
+///             println!("Error: {e:?}")
+///         }
+///     }
+///
+///     Ok(())
+/// }
+/// ```
 #[derive(Debug)]
 pub struct SimConnect {
-    pub handle: std::ptr::NonNull<c_void>,
-    pub registered_objects: Vec<String>,
+    handle: std::ptr::NonNull<c_void>,
+    registered_objects: Vec<String>,
 }
 
 impl SimConnect {
+    /// Create a new SimConnect SDK client.
     #[tracing::instrument(name = "SimConnect::new")]
     pub fn new(name: &str) -> Result<Self, SimConnectError> {
         let mut handle = std::ptr::null_mut();
@@ -182,6 +234,9 @@ impl SimConnect {
         Ok(())
     }
 
+    /// Receive the next SimConnect message.
+    /// This is a non-blocking function. If there are no messages to receive, it will return None immediately.
+    /// When called in a loop, it is recommended to use a short sleep time.
     pub fn get_next_dispatch(&self) -> Result<Option<Notification>, SimConnectError> {
         let mut data_buf: *mut bindings::SIMCONNECT_RECV = std::ptr::null_mut();
         let mut size_buf: bindings::DWORD = 32;