From 610b9faea80b2bfabcd9b731a384b1a2d09ca3ab Mon Sep 17 00:00:00 2001 From: Alex <7845120+newAM@users.noreply.github.com> Date: Sat, 30 Jan 2021 09:27:37 -0800 Subject: [PATCH] Improved documentation annotations for platform-specific features. (#20) * Improved documentation annotations for platform-specific features. * Fix clippy lints. --- .github/workflows/ci.yml | 2 +- CHANGELOG.md | 6 ++++-- Cargo.toml | 5 ++++- README.md | 2 +- src/lib.rs | 32 +++++++++++++++++++------------- src/types.rs | 8 ++++---- src/util.rs | 3 +-- 7 files changed, 34 insertions(+), 24 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index ec275d4..5cb5aa4 100644 --- a/.github/workflows/ci.yml +++ b/.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 diff --git a/CHANGELOG.md b/CHANGELOG.md index 549747a..62fa760 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/Cargo.toml b/Cargo.toml index bf7c2a6..88ace76 100644 --- a/Cargo.toml +++ b/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. "] 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"] diff --git a/README.md b/README.md index aa3e6de..54affc4 100644 --- a/README.md +++ b/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. diff --git a/src/lib.rs b/src/lib.rs index b05ae21..b4e50b4 100644 --- a/src/lib.rs +++ b/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 { /// 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 { /// 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> { /// 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, 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()) }; diff --git a/src/types.rs b/src/types.rs index f6ad857..7bffe8c 100644 --- a/src/types.rs +++ b/src/types.rs @@ -862,10 +862,10 @@ impl EepromStrings { serial_number: &[i8], ) -> Result { 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`, diff --git a/src/util.rs b/src/util.rs index 0311d4a..0419ae7 100644 --- a/src/util.rs +++ b/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::(), std::mem::size_of::()); - 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)]