add cfg docs

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"]
+

src/lib.rs

@@ -53,12 +53,13 @@
 //! ```
 //!
 //! # Features
-//! - **r2r_msg** — Integration for the ROS2 library [r2r](https://github.com/sequenceplanner/r2r).
+//! - 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.
-//! - **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** (default) — Needed for the `_vec` functions and helpful custom point derive macros for the [`PointConvertible`] trait.
+//! - 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 to be enabled.
+//! - rayon — Parallel iterator support for `_par_iter` functions. [`PointCloud2Msg::try_from_par_iter`] additionally needs the 'derive' feature.
-//! - **nalgebra** — When enabled, predefined points offer a `xyz()` getter returning `nalgebra::Point3`.
+//! - 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<const N: usize, C>(
         iterable: impl rayon::iter::ParallelIterator<Item = C>,
     ) -> Result<Self, MsgConversionError>
@@ -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<const N: usize, C>(vec: Vec<C>) -> Result<Self, MsgConversionError>
     where
         C: PointConvertible<N>,
@@ -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<const N: usize, C>(self) -> Result<Vec<C>, MsgConversionError>
     where
         C: PointConvertible<N>,
@@ -746,6 +752,7 @@ impl PointCloud2Msg {
     /// let cloud_points_out = msg_out.try_into_par_iter().unwrap().collect::<Vec<PointXYZ>>();
     /// assert_eq!(2, cloud_points_out.len());
     /// ```
+    #[cfg_attr(docsrs, doc(cfg(feature = "rayon")))]
     #[cfg(feature = "rayon")]
     pub fn try_into_par_iter<const N: usize, C>(
         self,
@@ -828,6 +835,7 @@ impl<const N: usize> From<[PointData; N]> for RPCL2Point<N> {
 ///
 /// impl PointConvertible<4> for MyPointXYZI {}
 /// ```
+#[cfg_attr(docsrs, doc(cfg(not(feature = "derive"))))]
 #[cfg(not(feature = "derive"))]
 pub trait PointConvertible<const N: usize>:
     From<RPCL2Point<N>> + Into<RPCL2Point<N>> + Fields<N> + Clone + Default
@@ -889,6 +897,7 @@ pub trait PointConvertible<const N: usize>:
 ///
 /// impl PointConvertible<4> for MyPointXYZI {}
 /// ```
+#[cfg_attr(docsrs, doc(cfg(feature = "derive")))]
 #[cfg(feature = "derive")]
 pub trait PointConvertible<const N: usize>:
     type_layout::TypeLayout + From<RPCL2Point<N>> + Into<RPCL2Point<N>> + Fields<N> + Default
@@ -1359,7 +1368,7 @@ impl From<points::RGB> 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<PointDataBuffer> {
     fn from_be_bytes(bytes: PointDataBuffer) -> Self;
     fn from_le_bytes(bytes: PointDataBuffer) -> Self;

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<f32> {
         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<f32> {
         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<f32> {
         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<f32> {
         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<f32> {
         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<f32> {
         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<f32> {
         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<f32> {
         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<f32> {
         nalgebra::Point3::new(self.x, self.y, self.z)
     }