Update and document the revised API

Author: foresterre

crates/rust-toolchain/src/channel.rs

@@ -72,11 +72,31 @@ impl Channel {
     pub fn is_nightly(&self) -> bool {
         matches!(self, Self::Nightly(_))
     }
+
+    /// Returns the release version, or None, if it's a nightly release.
+    pub fn version(&self) -> Option<RustVersion> {
+        match self {
+            Channel::Stable(v) => Some(v.version),
+            Channel::Beta(v) => Some(v.version),
+            Channel::Nightly(_) => None,
+        }
+    }
+
+    /// Returns the release date, or
+    pub fn date(&self) -> Option<Date> {
+        match self {
+            Channel::Stable(_) => None,
+            Channel::Beta(_) => None,
+            Channel::Nightly(v) => Some(v.date.clone()),
+        }
+    }
 }
 
 #[cfg(test)]
 mod tests {
     use super::*;
+    use crate::{Date, RustVersion};
+    use yare::parameterized;
 
     #[test]
     fn create_channel_stable() {
@@ -104,4 +124,13 @@ mod tests {
         assert!(!stable.is_beta());
         assert!(stable.is_nightly());
     }
+
+    #[parameterized(
+        stable = { Channel::stable("1.2.3".parse().unwrap()), Some(RustVersion::new(1,2,3)) },
+        beta = { Channel::beta("1.2.3".parse().unwrap()), Some(RustVersion::new(1,2,3)) },
+        nightly = { Channel::nightly(Date::new(2024, 1, 1)), None }
+    )]
+    fn version(c: Channel, expected: Option<RustVersion>) {
+        assert_eq!(c.version(), expected)
+    }
 }

crates/rust-toolchain/src/channel/beta.rs

@@ -5,21 +5,23 @@ use crate::RustVersion;
 /// [`channel`]: https://rust-lang.github.io/rustup/concepts/channels.html
 #[derive(Clone, Debug, Eq, Hash, PartialEq, PartialOrd, Ord)]
 pub struct Beta {
+    /// The three component Rust version
     pub version: RustVersion,
+    /// The nth pre-release beta version, if any
     pub prerelease: Option<u32>,
 }
 
 #[cfg(test)]
 mod tests {
-    use crate::{Beta, RustVersion};
+    use crate::{channel::Beta, RustVersion};
 
     #[yare::parameterized(
         day1 = { RustVersion::new(0, 0, 0), RustVersion::new(0, 0, 1) },
         month1 = { RustVersion::new(0, 0, 0), RustVersion::new(0, 1, 0) },
         year1 = { RustVersion::new(0, 0, 0), RustVersion::new(1, 0, 0) },
-        month_trumps_day = { RustVersion::new(0, 0, 999), RustVersion::new(0, 1, 0) },
-        year_trumps_day = { RustVersion::new(0, 0, 999), RustVersion::new(1, 0, 0) },
-        year_trumps_month = { RustVersion::new(0, 999, 0), RustVersion::new(1, 0, 0) },
+        month_over_day = { RustVersion::new(0, 0, 999), RustVersion::new(0, 1, 0) },
+        year_over_day = { RustVersion::new(0, 0, 999), RustVersion::new(1, 0, 0) },
+        year_over_month = { RustVersion::new(0, 999, 0), RustVersion::new(1, 0, 0) },
     )]
     fn ord(left: RustVersion, right: RustVersion) {
         let left = Beta {

crates/rust-toolchain/src/channel/nightly.rs

@@ -5,20 +5,21 @@ use crate::Date;
 /// [`channel`]: https://rust-lang.github.io/rustup/concepts/channels.html
 #[derive(Clone, Debug, Eq, Hash, PartialEq, PartialOrd, Ord)]
 pub struct Nightly {
+    /// A short YYYY-MM-DD associated date
     pub date: Date,
 }
 
 #[cfg(test)]
 mod tests {
-    use crate::{Date, Nightly};
+    use crate::{channel::Nightly, Date};
 
     #[yare::parameterized(
         patch1 = { Date::new(0, 0, 0), Date::new(0, 0, 1) },
         minor1 = { Date::new(0, 0, 0), Date::new(0, 1, 0) },
         major1 = { Date::new(0, 0, 0), Date::new(1, 0, 0) },
-        minor_trumps_patch = { Date::new(0, 0, 99), Date::new(0, 1, 0) },
-        major_trumps_patch = { Date::new(0, 0, 99), Date::new(1, 0, 0) },
-        major_trumps_minor = { Date::new(0, 99, 0), Date::new(1, 0, 0) },
+        minor_over_patch = { Date::new(0, 0, 99), Date::new(0, 1, 0) },
+        major_over_patch = { Date::new(0, 0, 99), Date::new(1, 0, 0) },
+        major_over_minor = { Date::new(0, 99, 0), Date::new(1, 0, 0) },
     )]
     fn ord(left: Date, right: Date) {
         let left = Nightly { date: left };

crates/rust-toolchain/src/channel/stable.rs

@@ -5,20 +5,21 @@ use crate::RustVersion;
 /// [`channel`]: https://rust-lang.github.io/rustup/concepts/channels.html
 #[derive(Clone, Debug, Eq, Hash, PartialEq, PartialOrd, Ord)]
 pub struct Stable {
+    /// The three component Rust version
     pub version: RustVersion,
 }
 
 #[cfg(test)]
 mod tests {
-    use crate::{RustVersion, Stable};
+    use crate::{channel::Stable, RustVersion};
 
     #[yare::parameterized(
         patch1 = { RustVersion::new(0, 0, 0), RustVersion::new(0, 0, 1) },
         minor1 = { RustVersion::new(0, 0, 0), RustVersion::new(0, 1, 0) },
         major1 = { RustVersion::new(0, 0, 0), RustVersion::new(1, 0, 0) },
-        minor_trumps_patch = { RustVersion::new(0, 0, 999), RustVersion::new(0, 1, 0) },
-        major_trumps_patch = { RustVersion::new(0, 0, 999), RustVersion::new(1, 0, 0) },
-        major_trumps_minor = { RustVersion::new(0, 999, 0), RustVersion::new(1, 0, 0) },
+        minor_over_patch = { RustVersion::new(0, 0, 999), RustVersion::new(0, 1, 0) },
+        major_over_patch = { RustVersion::new(0, 0, 999), RustVersion::new(1, 0, 0) },
+        major_over_minor = { RustVersion::new(0, 999, 0), RustVersion::new(1, 0, 0) },
     )]
     fn ord(left: RustVersion, right: RustVersion) {
         let left = Stable { version: left };

crates/rust-toolchain/src/component.rs

@@ -1,4 +1,3 @@
-use crate::{Beta, Nightly, Stable};
 use std::borrow::Cow;
 
 /// A toolchain component
@@ -15,10 +14,12 @@ pub struct Component {
 }
 
 impl Component {
+    /// Create a new Component instance
     pub fn new(name: impl Into<Cow<'static, str>>) -> Self {
         Self { name: name.into() }
     }
 
+    /// The name of the component
     pub fn name(&self) -> &str {
         self.name.as_ref()
     }

crates/rust-toolchain/src/date.rs

@@ -1,6 +1,16 @@
 use std::fmt;
 
-/// A release date for a Rust release.
+/// A release date for a Rust toolchain.
+///
+/// Nightly toolchains use a date as version instead of a semver number.
+/// This Date should be regarded as a form of a version number, just like semver.
+///
+/// For full-featured dates, it is recommended to use a dedicated library
+/// like [`time`], [`chrono`] or [`jiff`].
+///
+/// [`time`]: https://docs.rs/time/latest/time/
+/// [`chrono`]: https://docs.rs/chrono/latest/chrono/
+/// [`jiff`]:https://docs.rs/jiff/latest/jiff/
 #[derive(Clone, Debug, Eq, Hash, PartialEq, Ord, PartialOrd)]
 pub struct Date {
     date: DateImpl,
@@ -24,6 +34,21 @@ impl Date {
         }
     }
 
+    /// The year
+    pub fn year(&self) -> u16 {
+        self.date.year
+    }
+
+    /// The month
+    pub fn month(&self) -> u8 {
+        self.date.month
+    }
+
+    /// The day
+    pub fn day(&self) -> u8 {
+        self.date.day
+    }
+
     /// Prints a yyyy-mm-dd representation of a release date.
     ///
     /// This representation may, just like [`Date`], be not a valid date

crates/rust-toolchain/src/lib.rs

@@ -1,33 +1,41 @@
 //! # rust-toolchain
 //!
-//! The `rust-toolchain` crate defines a set of types which describe a Rust toolchain.
+//! The [`rust-toolchain`] crate defines a set of types which model a Rust toolchain.
+//!
 //! While there is no definitive spec which defines what a "Rust toolchain" is,
-//! we try to follow the official Rust release process as closely as possible.
-//! The [`rustup`] project has written down a rough specification for [`toolchains`] used
-//! by the Rust project. In the initial version, we will follow this spec, but disregard custom
-//! toolchains altogether, in the name of simplicity.
+//! it tries to follow official Rust sources as closely as possible.
+//!
+//! The project is currently primarily modelled around the rough [`toolchain`]
+//! specification written by the [`rustup`] developers. For now, we have disregarded
+//! custom toolchains altogether though, both in the name of simplicity, and because
+//! the current users didn't really need it yet. If you would like to see it added,
+//! please open an issue (preferably including your use case :)).
 //!
 //! This project is part of the [`rust-releases`] and [`cargo-msrv`] projects.
-//! In case you have a feature request, question, bug, or have another reason to contact the developers,
-//! please, create a new issue at the `rust-releases` [`repository`].
 //!
+//! In case you have a feature request, question, bug, or have another reason to
+//! contact the developers, please create a new issue at the `rust-releases` [`repository`].
+//!
+//! [`rust-toolchain`]: https://docs.rs/rust-toolchain/latest/rust_toolchain/
 //! [`rustup`]: https://github.com/rust-lang/rustup
-//! [`toolchains`]: https://rust-lang.github.io/rustup/concepts/toolchains.html
+//! [`toolchain`]: https://rust-lang.github.io/rustup/concepts/toolchains.html
 //! [`rust-releases`]: https://github.com/foresterre/rust-releases
 //! [`cargo-msrv`]: https://github.com/foresterre/cargo-msrv
 //! [`repository`]: https://github.com/foresterre/rust-releases/issues
 // #![deny(missing_docs)]
 #![warn(clippy::all)]
 #![deny(unsafe_code)]
+#![deny(missing_docs)]
 
-mod channel;
+/// Rust release channels, such as stable, beta and nightly.
+pub mod channel;
 mod component;
 mod date;
 mod target;
 mod toolchain;
 mod version;
 
-pub use channel::{Channel, *};
+pub use channel::Channel;
 pub use component::Component;
 pub use date::Date;
 pub use target::Target;

crates/rust-toolchain/src/target.rs

@@ -1,6 +1,7 @@
+use std::fmt;
 use std::str::FromStr;
 
-/// A Rust toolchain
+/// A target platform
 ///
 /// Commonly represented as a [`target triple`]. A target triple consists of three (or four) components: the
 /// architecture component, the vendor component, the operating system component and optionally
@@ -11,22 +12,22 @@ use std::str::FromStr;
 /// - [`RFC 0131: target specification`]
 /// - [`rustup concepts: toolchains`]
 /// - [`rustup component history`]
+/// - [`rustc platform support`]
 ///
 /// [`target triple`]: https://github.com/rust-lang/rfcs/blob/master/text/0131-target-specification.md#detailed-design
 /// [`RFC 0131: target specification`]: https://github.com/rust-lang/rfcs/blob/master/text/0131-target-specification.md#detailed-design
 /// [`rustup concepts: toolchains`]: https://rust-lang.github.io/rustup/concepts/toolchains.html
 /// [`rustup component history`]: https://rust-lang.github.io/rustup-components-history/
-// Extra information may be found here:
-// - https://doc.rust-lang.org/rustc/platform-support.html
-// - https://rust-lang.github.io/rustup/concepts/toolchains.html
+/// [`rustc platform support`]: https://doc.rust-lang.org/rustc/platform-support.html
 #[derive(Clone, Debug, Eq, Hash, PartialEq)]
 pub struct Target {
     target: target_lexicon::Triple,
 }
 
 impl Target {
-    /// Create a new `Target` instance which represents the `host` platform on which the compiler
-    /// runs.
+    /// Create a new `Target` instance which represents the `host` platform.
+    ///
+    /// The platform on which this library is compiled, will be the `host` platform.
     pub const fn host() -> Self {
         Self {
             target: target_lexicon::HOST,
@@ -58,6 +59,13 @@ impl Target {
     }
 }
 
+impl fmt::Display for Target {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "{}", self.target)
+    }
+}
+
+/// Errors which may occur while parsing a [`Target`].
 #[derive(Debug, thiserror::Error)]
 #[non_exhaustive]
 pub enum ParseError {
@@ -104,4 +112,11 @@ mod tests {
 
         assert_eq!(this_platform, expected);
     }
+
+    #[test]
+    fn to_string() {
+        let target = Target::try_from_target_triple("x86_64-unknown-linux-gnu").unwrap();
+
+        assert_eq!(target.to_string(), "x86_64-unknown-linux-gnu");
+    }
 }