Improved documentation annotations for platform-specific features. (f…

…tdi-rs#20)

* Improved documentation annotations for platform-specific features.

* Fix clippy lints.

.github/workflows/ci.yml

@@ -76,7 +76,7 @@ jobs:
       - uses: actions-rs/clippy-check@v1
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
-          args: --all-features
+          args: --all-features -- -D warnings
 
   docs:
     name: docs

CHANGELOG.md

@@ -4,9 +4,10 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.24.1] - 2021-01-30
 ### Changed
 - Streamlined `udev` rules recommendations.
+- Improved documentation annotations for platform-specific features.
 
 ### Fixed
 - Fixed compilation errors for `aarch64-unknown-linux` targets.
@@ -71,7 +72,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## Prior releases
 A changelog was not kept for prior releases.
 
-[Unreleased]: https://github.com/newAM/libftd2xx-rs/compare/0.24.0...HEAD
+[Unreleased]: https://github.com/newAM/libftd2xx-rs/compare/0.24.1...HEAD
+[0.24.1]: https://github.com/newAM/libftd2xx-rs/compare/0.24.0...0.24.1
 [0.24.0]: https://github.com/newAM/libftd2xx-rs/compare/0.23.0...0.24.0
 [0.23.0]: https://github.com/newAM/libftd2xx-rs/compare/0.22.0...0.23.0
 [0.22.0]: https://github.com/newAM/libftd2xx-rs/compare/0.21.1...0.22.0

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "libftd2xx"
-version = "0.24.0" # remember to update html_root_url
+version = "0.24.1" # remember to update html_root_url
 authors = ["Alex M. <[email protected]>"]
 edition = "2018"
 description = "Rust safe wrapper around the libftd2xx-ffi crate."
@@ -21,3 +21,6 @@ paste = "^1.0.0"
 
 [dev-dependencies]
 version-sync = "~0.9.1"
+
+[package.metadata.docs.rs]
+rustdoc-args = ["--cfg", "docsrs"]

README.md

@@ -17,7 +17,7 @@ permission from FTDI.
 
 ```toml
 [dependencies]
-libftd2xx = "~0.24.0"
+libftd2xx = "~0.24.1"
 ```
 
 This is a basic example to get your started.

src/lib.rs

@@ -10,7 +10,7 @@
 //!
 //! ```toml
 //! [dependencies]
-//! libftd2xx = "~0.24.0"
+//! libftd2xx = "~0.24.1"
 //! ```
 //!
 //! This is a basic example to get your started.
@@ -69,7 +69,8 @@
 //! [libftd2xx-ffi]: https://github.com/newAM/libftd2xx-ffi-rs
 //! [setup executable]: https://www.ftdichip.com/Drivers/CDM/CDM21228_Setup.zip
 //! [udev]: https://en.wikipedia.org/wiki/Udev
-#![doc(html_root_url = "https://docs.rs/libftd2xx/0.24.0")]
+#![cfg_attr(docsrs, feature(doc_cfg))]
+#![doc(html_root_url = "https://docs.rs/libftd2xx/0.24.1")]
 #![deny(missing_docs)]
 
 mod errors;
@@ -167,7 +168,7 @@ pub fn num_devices() -> Result<u32, FtStatus> {
 /// A command to include a custom VID and PID combination within the internal
 /// device list table.
 ///
-/// This function is available on Linux only.
+/// This function is available on Linux or mac only.
 ///
 /// This will allow the driver to load for the specified VID and PID
 /// combination.
@@ -183,7 +184,8 @@ pub fn num_devices() -> Result<u32, FtStatus> {
 /// assert_eq!(pid, 0x1234);
 /// # Ok::<(), libftd2xx::FtStatus>(())
 /// ```
-#[cfg(any(target_os = "linux", target_os = "mac"))]
+#[cfg(any(unix, doc))]
+#[cfg_attr(docsrs, doc(cfg(unix)))]
 pub fn set_vid_pid(vid: u16, pid: u16) -> Result<(), FtStatus> {
     trace!("FT_SetVIDPID({}, {})", vid, pid);
     let status: FT_STATUS = unsafe { FT_SetVIDPID(vid.into(), pid.into()) };
@@ -193,7 +195,7 @@ pub fn set_vid_pid(vid: u16, pid: u16) -> Result<(), FtStatus> {
 /// A command to retrieve the current VID and PID combination from within the
 /// internal device list table.
 ///
-/// This function is available on Linux only.
+/// This function is available on Linux or mac only.
 ///
 /// This `vid` and `pid` are set by [`set_vid_pid`].
 ///
@@ -213,7 +215,8 @@ pub fn set_vid_pid(vid: u16, pid: u16) -> Result<(), FtStatus> {
 /// ```
 ///
 /// [`set_vid_pid`]: ./fn.set_vid_pid.html
-#[cfg(any(target_os = "linux", target_os = "mac"))]
+#[cfg(any(unix, doc))]
+#[cfg_attr(docsrs, doc(cfg(unix)))]
 pub fn vid_pid() -> Result<(u32, u32), FtStatus> {
     let mut vid: u32 = 0;
     let mut pid: u32 = 0;
@@ -453,7 +456,8 @@ pub fn list_devices_fs() -> io::Result<Vec<DeviceInfo>> {
 /// libftd2xx::rescan()?;
 /// # Ok::<(), libftd2xx::FtStatus>(())
 /// ```
-#[cfg(target_os = "windows")]
+#[cfg(all(any(windows, doc), not(doctest)))]
+#[cfg_attr(docsrs, doc(cfg(windows)))]
 pub fn rescan() -> Result<(), FtStatus> {
     trace!("FT_Rescan()");
     let status: FT_STATUS = unsafe { FT_Rescan() };
@@ -1478,7 +1482,8 @@ pub trait FtdiCommon {
     /// }
     /// # Ok::<(), libftd2xx::FtStatus>(())
     /// ```
-    #[cfg(target_os = "windows")]
+    #[cfg(all(any(windows, doc), not(doctest)))]
+    #[cfg_attr(docsrs, doc(cfg(windows)))]
     fn com_port_number(&mut self) -> Result<Option<u32>, FtStatus> {
         let mut num: i32 = -1;
         trace!("FT_GetComPortNumber({:?}, _)", self.handle());
@@ -1498,7 +1503,8 @@ pub trait FtdiCommon {
     /// This method is available on Windows only.
     ///
     /// This function is used to attempt to recover the device upon failure.
-    /// For the equivalent of a unplug-replug event use [`cycle_port`].
+    /// For the equivalent of a unplug-replug event use
+    /// [`FtdiCommon::cycle_port`].
     ///
     /// # Example
     ///
@@ -1509,9 +1515,8 @@ pub trait FtdiCommon {
     /// ft.reset_port()?;
     /// # Ok::<(), libftd2xx::FtStatus>(())
     /// ```
-    ///
-    /// [`cycle_port`]: #cycle_port
-    #[cfg(target_os = "windows")]
+    #[cfg(all(any(windows, doc), not(doctest)))]
+    #[cfg_attr(docsrs, doc(cfg(windows)))]
     fn reset_port(&mut self) -> Result<(), FtStatus> {
         trace!("FT_ResetPort({:?})", self.handle());
         let status: FT_STATUS = unsafe { FT_ResetPort(self.handle()) };
@@ -1548,7 +1553,8 @@ pub trait FtdiCommon {
     /// ft.cycle_port()?;
     /// # Ok::<(), libftd2xx::FtStatus>(())
     /// ```
-    #[cfg(target_os = "windows")]
+    #[cfg(all(any(windows, doc), not(doctest)))]
+    #[cfg_attr(docsrs, doc(cfg(windows)))]
     fn cycle_port(&mut self) -> Result<(), FtStatus> {
         trace!("FT_CyclePort({:?})", self.handle());
         let status: FT_STATUS = unsafe { FT_CyclePort(self.handle()) };

src/types.rs

@@ -862,10 +862,10 @@ impl EepromStrings {
         serial_number: &[i8],
     ) -> Result<Self, EepromStringsError> {
         let mut ret = Self::default();
-        ret.set_manufacturer(slice_into_string(manufacturer.as_ref()))?;
-        ret.set_manufacturer_id(slice_into_string(manufacturer_id.as_ref()))?;
-        ret.set_description(slice_into_string(description.as_ref()))?;
-        ret.set_serial_number(slice_into_string(serial_number.as_ref()))?;
+        ret.set_manufacturer(slice_into_string(manufacturer))?;
+        ret.set_manufacturer_id(slice_into_string(manufacturer_id))?;
+        ret.set_description(slice_into_string(description))?;
+        ret.set_serial_number(slice_into_string(serial_number))?;
         Ok(ret)
     }
     /// Total length of the `manufacturer`, `manufacturer_id`,

src/util.rs

@@ -34,8 +34,7 @@ where
     // Safety: The trait bounds for T are only implemented for u8 and i8, which
     // are equal size, and are therefore safe to transmute.
     debug_assert_eq!(std::mem::size_of::<T>(), std::mem::size_of::<u8>());
-    String::from_utf8_lossy(unsafe { std::mem::transmute::<&[T], &[u8]>(&array[0..idx]) })
-        .to_string()
+    String::from_utf8_lossy(unsafe { &*(&array[0..idx] as *const [T] as *const [u8]) }).to_string()
 }
 
 #[cfg(test)]