Merge pull request #140 from stphnt/scope-rework

Refactor ascii::chain::scope and improve its documentation

src/ascii/chain/scope.rs

@@ -1,4 +1,47 @@
 //! Types and traits for marking the scope of a type (i.e. whether an item is axis-scope or device-scope).
+//!
+//! The scope of an item is determined by whether it implements [`AxisScope`] or [`DeviceScope`].
+//!
+//! In some cases, types/functions need to change the required scope of their parameters based on a type
+//! parameter. In such cases, the [`RequiresAxisScope`] and [`RequiresDeviceScope`] types can be used in
+//! conjunction with either of the [`RequiredScopeSatisfiedBy`] or [`SatisfiesRequiredScope`] trait bounds:
+//!
+//! ```
+//! # use zproto::ascii::chain::scope::*;
+//! struct Foo<R>(std::marker::PhantomData<R>);
+//! impl<R> Foo<R> {
+//!     fn bar<T: SatisfiesRequiredScope<R>>(_: T) { /* ... */ }
+//! }
+//!
+//! struct AxisThing;
+//! impl AxisScope for AxisThing {};
+//!
+//! struct DeviceThing;
+//! impl DeviceScope for DeviceThing {};
+//!
+//! Foo::<RequiresAxisScope>::bar(AxisThing);      // OK
+//! // Foo::<RequiresAxisScope>::bar(DeviceThing); // Compilation error.
+//! // Foo::<RequiresDeviceScope>::bar(AxisThing); // Compilation error.
+//! Foo::<RequiresDeviceScope>::bar(DeviceThing);  // OK
+//! ```
+// It may be tempting to replace the scope requirement types and associated traits with one trait,
+// something like:
+//
+// ```
+// pub trait SameScope<A, B> {}
+// ```
+//
+// And then implement it for all types A and B where both types implement the same scope trait.
+// However, this will result in conflicting implementations,
+//
+// ```
+// impl<A, B> SameScope<A, B> for A where A: DeviceScope, B: DeviceScope {}
+// impl<A, B> SameScope<A, B> for A where A: AxisScope, B: AxisScope {} // conflicting
+// implementation
+// ```
+//
+// To avoid this, the traits need to be implement on concrete types, hence the Requires*Scope
+// types.
 
 /// A marker trait indicating that a type represents an axis-scope item.
 pub trait AxisScope {}
@@ -10,33 +53,75 @@ pub trait DeviceScope {}
 impl<T> DeviceScope for &T where T: DeviceScope {}
 impl<T> DeviceScope for &mut T where T: DeviceScope {}
 
-/// A concrete marker type for indicate that a wrapping type is axis-scope.
+/// A marker type indicating a type requires other types to satisfy an [`AxisScope`] bound.
+///
+/// To fully achieve this behaviour, it must be used in conjunction with one of
+/// [`RequiredScopeSatisfiedBy`] or [`SatisfiesRequiredScope`]. See the [module] level
+/// documentation for details.
+///
+/// [module]: crate::ascii::chain::scope
 #[derive(Debug)]
-pub enum AxisScopeMarker {}
-impl AxisScope for AxisScopeMarker {}
+pub enum RequiresAxisScope {}
+impl AxisScope for RequiresAxisScope {}
 
-/// A concrete marker type for indicate that a wrapping type is device-scope.
+/// A marker type indicating a type requires other types to satisfy a [`DeviceScope`] bounds.
+///
+/// To fully achieve this behaviour, it must be used in conjunction with one of
+/// [`RequiredScopeSatisfiedBy`] or [`SatisfiesRequiredScope`]. See the [module] level
+/// documentation for details.
+///
+/// [module]: crate::ascii::chain::scope
 #[derive(Debug)]
-pub enum DeviceScopeMarker {}
-impl DeviceScope for DeviceScopeMarker {}
+pub enum RequiresDeviceScope {}
+impl DeviceScope for RequiresDeviceScope {}
 
-/// A marker trait indicating a type marker has the same scope as some other type `T`.
+/// A marker trait indicating a type indicating a scope requirement is satisfied by the type `T`.
+///
+/// This allows the scope requirement to be defined by a type parameter, otherwise the
+/// [`AxisScope`] or [`DeviceScope`] traits should be used as a bound directly.
 ///
-/// This should be used as a bounds on one of the marker types `AxisScopeMarker`
-/// or `DeviceScopeMarker`.
+/// ```
+/// # use zproto::ascii::chain::scope::RequiredScopeSatisfiedBy;
+/// # fn foo<T, R>(_: T, _: R)
+/// where
+///     R: RequiredScopeSatisfiedBy<T>
+///     // Read as "The scope required by type R is satisfied by type T," where R must be
+///     // either RequiresAxisScope or RequiresDeviceScope.
+/// # {}
+/// ```
 ///
-/// For the inverse, see [`SameScopeAsMarker`].
-pub trait MarksScopeOf<T> {}
+/// The inverse bound is defined by [`SatisfiesRequiredScope`].
+///
+/// See the [module] level documentation for more details.
+///
+/// [module]: crate::ascii::chain::scope
+pub trait RequiredScopeSatisfiedBy<T> {}
 
-impl<T> MarksScopeOf<T> for AxisScopeMarker where T: AxisScope {}
-impl<T> MarksScopeOf<T> for DeviceScopeMarker where T: DeviceScope {}
+impl<T> RequiredScopeSatisfiedBy<T> for RequiresAxisScope where T: AxisScope {}
+impl<T> RequiredScopeSatisfiedBy<T> for RequiresDeviceScope where T: DeviceScope {}
 
-/// A marker trait indicating a type has the same scope as some marker type `T`.
+/// A marker trait indicating a type satisfies the scope requirement of `T`, which must be either
+/// [`RequiresAxisScope`] and [`RequiresDeviceScope`].
+///
+/// This allows the scope requirement to be defined by a type parameter, otherwise the
+/// [`AxisScope`] or [`DeviceScope`] traits should be used as a bound directly.
+///
+/// ```
+/// # use zproto::ascii::chain::scope::SatisfiesRequiredScope;
+/// # fn foo<T, R>(_: T, _: R)
+/// where
+///     T: SatisfiesRequiredScope<R>
+///     // Read as "T satisfies the scope required by type R," where R must be either
+///     // RequiresScopeAxis or RequiresDeviceAxis.
+/// # {}
+/// ```
+///
+/// The inverse bound is defined by [`RequiredScopeSatisfiedBy`].
 ///
-/// This should be used as a bounds on a type other than `AxisScopeMarker` and `DeviceScopeMarker`.
+/// See the [module] level documentation for more details.
 ///
-/// For the inverse, see [`MarksScopeOf`].
-pub trait SameScopeAsMarker<T> {}
+/// [module]: crate::ascii::chain::scope
+pub trait SatisfiesRequiredScope<T> {}
 
-impl<T> SameScopeAsMarker<AxisScopeMarker> for T where T: AxisScope {}
-impl<T> SameScopeAsMarker<DeviceScopeMarker> for T where T: DeviceScope {}
+impl<T> SatisfiesRequiredScope<RequiresAxisScope> for T where T: AxisScope {}
+impl<T> SatisfiesRequiredScope<RequiresDeviceScope> for T where T: DeviceScope {}

src/ascii/chain/setting.rs

@@ -5,7 +5,7 @@ use crate::{
 		chain::{
 			data_type::DataType,
 			info::ChainInfo,
-			scope::{AxisScopeMarker, DeviceScopeMarker, SameScopeAsMarker},
+			scope::{RequiresAxisScope, RequiresDeviceScope, SatisfiesRequiredScope},
 			Axis, Device,
 		},
 		command::Target,
@@ -35,7 +35,7 @@ pub struct Settings<'a, B, P: SharedMut<Port<'a, B>>, S> {
 /// A type of [`Settings`] that gives access to axis-scope settings.
 ///
 /// For more details see [`Settings`].
-pub type AxisSettings<'a, B, P> = Settings<'a, B, P, AxisScopeMarker>;
+pub type AxisSettings<'a, B, P> = Settings<'a, B, P, RequiresAxisScope>;
 
 impl<'a, B, P> AxisSettings<'a, B, P>
 where
@@ -55,7 +55,7 @@ where
 /// A type of [`Settings`] that gives access to device-scope settings.
 ///
 /// For more details see [`Settings`].
-pub type DeviceSettings<'a, B, P> = Settings<'a, B, P, DeviceScopeMarker>;
+pub type DeviceSettings<'a, B, P> = Settings<'a, B, P, RequiresDeviceScope>;
 
 impl<'a, B, P> DeviceSettings<'a, B, P>
 where
@@ -82,7 +82,7 @@ where
 	/// The reply's warning flag and status fields are not checked. The reply is expected to be "OK".
 	pub fn get<T>(&self, setting: T) -> Result<<T::Type as DataType>::Owned, AsciiError>
 	where
-		T: Setting + SameScopeAsMarker<S>,
+		T: Setting + SatisfiesRequiredScope<S>,
 	{
 		let mut port = self.port.lock_mut().unwrap();
 		let reply = port
@@ -98,7 +98,7 @@ where
 		checker: impl check::Check<Reply>,
 	) -> Result<<T::Type as DataType>::Owned, AsciiError>
 	where
-		T: Setting + SameScopeAsMarker<S>,
+		T: Setting + SatisfiesRequiredScope<S>,
 	{
 		let mut port = self.port.lock_mut().unwrap();
 		let reply = port
@@ -112,7 +112,7 @@ where
 	/// The reply's warning flag and status fields are not checked. The reply is expected to be "OK".
 	pub fn set<T, V>(&self, setting: T, value: V) -> Result<(), AsciiError>
 	where
-		T: Setting + SameScopeAsMarker<S>,
+		T: Setting + SatisfiesRequiredScope<S>,
 		V: std::borrow::Borrow<<T::Type as DataType>::Borrowed>,
 	{
 		let mut port = self.port.lock_mut().unwrap();
@@ -137,7 +137,7 @@ where
 		checker: impl check::Check<Reply>,
 	) -> Result<(), AsciiError>
 	where
-		T: Setting + SameScopeAsMarker<S>,
+		T: Setting + SatisfiesRequiredScope<S>,
 		V: std::borrow::Borrow<<T::Type as DataType>::Borrowed>,
 	{
 		let mut port = self.port.lock_mut().unwrap();