From 94b35cc8227b8a6ddc9e00176570b2395bfd5248 Mon Sep 17 00:00:00 2001 From: stelzo Date: Wed, 15 May 2024 21:47:04 +0200 Subject: [PATCH] add cfg docs (#19) --- Cargo.toml | 2 ++ src/lib.rs | 23 ++++++++++++++++------- src/points.rs | 18 ++++++++++++++++++ 3 files changed, 36 insertions(+), 7 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index 063fed5..6f18424 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -58,3 +58,5 @@ default = ["derive", "std"] [package.metadata.docs.rs] features = ["derive", "nalgebra", "rayon"] default-target = "x86_64-unknown-linux-gnu" +rustdoc-args = ["--cfg", "docsrs"] + diff --git a/src/lib.rs b/src/lib.rs index 443e9ad..4851259 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -53,12 +53,13 @@ //! ``` //! //! # Features -//! - **r2r_msg** — Integration for the ROS2 library [r2r](https://github.com/sequenceplanner/r2r). -//! - **(rclrs_msg)** — Integration for ROS2 [rclrs](https://github.com/ros2-rust/ros2_rust) but it needs this [workaround](https://github.com/stelzo/ros_pointcloud2?tab=readme-ov-file#rclrs-ros2_rust) instead of a feature flag. -//! - **rosrust_msg** — Integration with the [rosrust](https://github.com/adnanademovic/rosrust) library for ROS1 message types. -//! - **derive** (default) — Needed for the `_vec` functions and helpful custom point derive macros for the [`PointConvertible`] trait. -//! - **rayon** — Parallel iterator support for `_par_iter` functions. [`PointCloud2Msg::try_from_par_iter`] additionally needs the 'derive' feature to be enabled. -//! - **nalgebra** — When enabled, predefined points offer a `xyz()` getter returning `nalgebra::Point3`. +//! - r2r_msg — Integration for the ROS2 library [r2r](https://github.com/sequenceplanner/r2r). +//! - rosrust_msg — Integration with the [rosrust](https://github.com/adnanademovic/rosrust) library for ROS1 message types. +//! - (rclrs_msg) — Integration for ROS2 [rclrs](https://github.com/ros2-rust/ros2_rust) but it currently needs [this workaround](https://github.com/stelzo/ros_pointcloud2?tab=readme-ov-file#rclrs-ros2_rust). +//! - derive *(enabled by default)* — Enables the `_vec` functions and offers helpful custom point derive macros for the [`PointConvertible`] trait. +//! - rayon — Parallel iterator support for `_par_iter` functions. [`PointCloud2Msg::try_from_par_iter`] additionally needs the 'derive' feature. +//! - nalgebra — Predefined points offer a nalgebra typed getter for coordinates (e.g. [`points::PointXYZ::xyz`]). +//! - std *(enabled by default)* — Use the standard library. Disable *all* features for `no_std` environments. //! //! # Custom Points //! Implement [`PointConvertible`] for your point with the `derive` feature or manually. @@ -126,6 +127,8 @@ //! } //! ``` #![crate_type = "lib"] +#![cfg_attr(docsrs, feature(doc_cfg))] +#![doc(html_root_url = "https://docs.rs/ros_pointcloud2/1.0.0-rc.1")] #![warn(clippy::print_stderr)] #![warn(clippy::print_stdout)] #![warn(clippy::unwrap_used)] @@ -551,6 +554,7 @@ impl PointCloud2Msg { /// Create a PointCloud2Msg from a parallel iterator. Requires the `rayon` and `derive` feature to be enabled. #[cfg(all(feature = "rayon", feature = "derive"))] + #[cfg_attr(docsrs, doc(cfg(all(feature = "rayon", feature = "derive"))))] pub fn try_from_par_iter( iterable: impl rayon::iter::ParallelIterator, ) -> Result @@ -578,6 +582,7 @@ impl PointCloud2Msg { /// # Errors /// Returns an error if the byte buffer does not match the expected layout or the message contains other discrepancies. #[cfg(feature = "derive")] + #[cfg_attr(docsrs, doc(cfg(feature = "derive")))] pub fn try_from_vec(vec: Vec) -> Result where C: PointConvertible, @@ -666,6 +671,7 @@ impl PointCloud2Msg { /// # Errors /// Returns an error if the byte buffer does not match the expected layout or the message contains other discrepancies. #[cfg(feature = "derive")] + #[cfg_attr(docsrs, doc(cfg(feature = "derive")))] pub fn try_into_vec(self) -> Result, MsgConversionError> where C: PointConvertible, @@ -746,6 +752,7 @@ impl PointCloud2Msg { /// let cloud_points_out = msg_out.try_into_par_iter().unwrap().collect::>(); /// assert_eq!(2, cloud_points_out.len()); /// ``` + #[cfg_attr(docsrs, doc(cfg(feature = "rayon")))] #[cfg(feature = "rayon")] pub fn try_into_par_iter( self, @@ -828,6 +835,7 @@ impl From<[PointData; N]> for RPCL2Point { /// /// impl PointConvertible<4> for MyPointXYZI {} /// ``` +#[cfg_attr(docsrs, doc(cfg(not(feature = "derive"))))] #[cfg(not(feature = "derive"))] pub trait PointConvertible: From> + Into> + Fields + Clone + Default @@ -889,6 +897,7 @@ pub trait PointConvertible: /// /// impl PointConvertible<4> for MyPointXYZI {} /// ``` +#[cfg_attr(docsrs, doc(cfg(feature = "derive")))] #[cfg(feature = "derive")] pub trait PointConvertible: type_layout::TypeLayout + From> + Into> + Fields + Default @@ -1359,7 +1368,7 @@ impl From for PointDataBuffer { } /// This trait is used to convert a byte slice to a primitive type. -/// All [`PointField`] types are supported. +/// All [`ros::PointFieldMsg`] types are supported. pub trait FromBytes: Default + Sized + Copy + GetFieldDatatype + Into { fn from_be_bytes(bytes: PointDataBuffer) -> Self; fn from_le_bytes(bytes: PointDataBuffer) -> Self; diff --git a/src/points.rs b/src/points.rs index b452bb4..d6ffa6b 100644 --- a/src/points.rs +++ b/src/points.rs @@ -144,7 +144,9 @@ impl PointXYZ { Self { x, y, z } } + /// Get the coordinates as a nalgebra Point3. #[cfg(feature = "nalgebra")] + #[cfg_attr(docsrs, doc(cfg(feature = "nalgebra")))] pub fn xyz(&self) -> nalgebra::Point3 { nalgebra::Point3::new(self.x, self.y, self.z) } @@ -190,7 +192,9 @@ impl PointXYZI { Self { x, y, z, intensity } } + /// Get the coordinates as a nalgebra Point3. #[cfg(feature = "nalgebra")] + #[cfg_attr(docsrs, doc(cfg(feature = "nalgebra")))] pub fn xyz(&self) -> nalgebra::Point3 { nalgebra::Point3::new(self.x, self.y, self.z) } @@ -247,7 +251,9 @@ impl PointXYZL { Self { x, y, z, label } } + /// Get the coordinates as a nalgebra Point3. #[cfg(feature = "nalgebra")] + #[cfg_attr(docsrs, doc(cfg(feature = "nalgebra")))] pub fn xyz(&self) -> nalgebra::Point3 { nalgebra::Point3::new(self.x, self.y, self.z) } @@ -321,7 +327,9 @@ impl PointXYZRGB { self.rgb.b() } + /// Get the coordinates as a nalgebra Point3. #[cfg(feature = "nalgebra")] + #[cfg_attr(docsrs, doc(cfg(feature = "nalgebra")))] pub fn xyz(&self) -> nalgebra::Point3 { nalgebra::Point3::new(self.x, self.y, self.z) } @@ -397,7 +405,9 @@ impl PointXYZRGBA { self.rgb.b() } + /// Get the coordinates as a nalgebra Point3. #[cfg(feature = "nalgebra")] + #[cfg_attr(docsrs, doc(cfg(feature = "nalgebra")))] pub fn xyz(&self) -> nalgebra::Point3 { nalgebra::Point3::new(self.x, self.y, self.z) } @@ -491,7 +501,9 @@ impl PointXYZRGBNormal { self.rgb.b() } + /// Get the coordinates as a nalgebra Point3. #[cfg(feature = "nalgebra")] + #[cfg_attr(docsrs, doc(cfg(feature = "nalgebra")))] pub fn xyz(&self) -> nalgebra::Point3 { nalgebra::Point3::new(self.x, self.y, self.z) } @@ -574,7 +586,9 @@ impl PointXYZINormal { } } + /// Get the coordinates as a nalgebra Point3. #[cfg(feature = "nalgebra")] + #[cfg_attr(docsrs, doc(cfg(feature = "nalgebra")))] pub fn xyz(&self) -> nalgebra::Point3 { nalgebra::Point3::new(self.x, self.y, self.z) } @@ -664,7 +678,9 @@ impl PointXYZRGBL { self.rgb.b() } + /// Get the coordinates as a nalgebra Point3. #[cfg(feature = "nalgebra")] + #[cfg_attr(docsrs, doc(cfg(feature = "nalgebra")))] pub fn xyz(&self) -> nalgebra::Point3 { nalgebra::Point3::new(self.x, self.y, self.z) } @@ -730,7 +746,9 @@ impl PointXYZNormal { } } + /// Get the coordinates as a nalgebra Point3. #[cfg(feature = "nalgebra")] + #[cfg_attr(docsrs, doc(cfg(feature = "nalgebra")))] pub fn xyz(&self) -> nalgebra::Point3 { nalgebra::Point3::new(self.x, self.y, self.z) }