More documentation improvements

README.md

@@ -50,9 +50,9 @@ async fn main() -> roslibrust::Result<()> {
     relay(ros).await?;
     }
 
+    // Relay messages over a zenoh connection compatible with zenoh-ros1-plugin / zenoh-ros1-bridge
     #[cfg(feature = "zenoh")]
     {
-    // Relay messages over a zenoh connection compatible with zenoh-ros1-plugin / zenoh-ros1-bridge
     let ros = roslibrust::zenoh::ZenohClient::new(zenoh::open(zenoh::Config::default()).await.unwrap());
     relay(ros).await?;
     }

roslibrust_codegen/src/lib.rs

@@ -1,3 +1,13 @@
+//! A library for generating rust type definitions from ROS IDL files
+//! Supports both ROS1 and ROS2.
+//! Generated types implement roslibrust's MessageType and ServiceType traits making them compatible with all roslibrust backends.
+//!
+//! This library is a pure rust implementation from scratch and requires no ROS installation.
+//!
+//! See [example_package](https://github.com/RosLibRust/roslibrust/tree/master/example_package) for how best to integrate this crate with build.rs
+//!
+//! Directly depending on this crate is not recommended. Instead access it via roslibrust with the `codegen` feature enabled.
+
 use log::*;
 use proc_macro2::TokenStream;
 use quote::quote;

roslibrust_zenoh/src/lib.rs

@@ -1,10 +1,13 @@
 //! A crate for interfacing to ROS1 via the [zenoh-ros1-plugin / zenoh-ros1-bridge](https://github.com/eclipse-zenoh/zenoh-plugin-ros1).
-
+//!
+//! It is not recommended to depend on this crate directly, but instead access it via [roslibrust](https://docs.rs/roslibrust/latest/roslibrust/) with the `zenoh` feature enabled.
 use roslibrust_common::*;
 
 use log::*;
 use zenoh::bytes::ZBytes;
 
+/// A wrapper around a normal zenoh session that adds roslibrust specific functionality.
+/// Should be created via [ZenohClient::new], and then used via the [TopicProvider] and [ServiceProvider] traits.
 pub struct ZenohClient {
     session: zenoh::Session,
 }
@@ -16,6 +19,8 @@ impl ZenohClient {
     }
 }
 
+/// The publisher type returned by [TopicProvider::advertise] on [ZenohClient]
+/// This type is self de-registering, and dropping the publisher will automatically un-advertise the topic.
 pub struct ZenohPublisher<T> {
     publisher: zenoh::pubsub::Publisher<'static>,
     _marker: std::marker::PhantomData<T>,
@@ -39,6 +44,11 @@ impl<T: RosMessageType> Publish<T> for ZenohPublisher<T> {
 // Using type alias here, I have no idea why zenoh has this type so deep
 type ZenohSubInner =
     zenoh::pubsub::Subscriber<zenoh::handlers::FifoChannelHandler<zenoh::sample::Sample>>;
+
+/// The subscriber type returned by [TopicProvider::subscribe] on [ZenohClient].
+/// This type is self de-registering, and dropping the subscriber will automatically unsubscribe from the topic.
+/// This type is generic on the message type that will be received.
+/// It is typically used with types generated by roslibrust's codegen.
 pub struct ZenohSubscriber<T> {
     subscriber: ZenohSubInner,
     _marker: std::marker::PhantomData<T>,
@@ -135,6 +145,8 @@ fn mangle_service(service: &str, type_str: &str, md5sum: &str) -> (String, Strin
     )
 }
 
+/// The client type returned by [ServiceProvider::service_client] on [ZenohClient]
+/// This type allows calling a service multiple times without re-negotiating the connection each time.
 pub struct ZenohServiceClient<T: RosServiceType> {
     session: zenoh::Session,
     zenoh_query: String,
@@ -194,8 +206,8 @@ impl<T: RosServiceType> Service<T> for ZenohServiceClient<T> {
     }
 }
 
-/// The "holder type" returned when advertising a service
-/// Dropping this will stop the service server
+/// The type returned by [ServiceProvider::advertise_service] on [ZenohClient].
+/// This type is self de-registering, and dropping the server will automatically un-advertise the service.
 pub struct ZenohServiceServer {
     // Dropping this will stop zenoh's declaration of the queryable
     _queryable: zenoh::query::Queryable<()>,