diff --git a/src/future-proofing.md b/src/future-proofing.md index e34edd5..8014b52 100644 --- a/src/future-proofing.md +++ b/src/future-proofing.md @@ -13,10 +13,6 @@ non-breaking way by using the sealed trait pattern. pub trait TheTrait: private::Sealed { // Zero or more methods that the user is allowed to call. fn ...(); - - // Zero or more private methods, not allowed for user to call. - #[doc(hidden)] - fn ...(); } // Implement for some types. @@ -25,19 +21,24 @@ impl TheTrait for usize { } mod private { - pub trait Sealed {} + pub trait Sealed { + // Zero or more private methods, not allowed for user to call. + fn ...(); + } // Implement for those same types, but no others. - impl Sealed for usize {} + impl Sealed for usize { + /* ... */ + } } ``` -The empty private `Sealed` supertrait cannot be named by downstream crates, so -we are guaranteed that implementations of `Sealed` (and therefore `TheTrait`) -only exist in the current crate. We are free to add methods to `TheTrait` in a +The private `Sealed` supertrait cannot be named by downstream crates, so we are +guaranteed that implementations of `Sealed` (and therefore `TheTrait`) only +exist in the current crate. We are free to add items to `TheTrait` in a non-breaking release even though that would ordinarily be a breaking change for -traits that are not sealed. Also we are free to change the signature of methods -that are not publicly documented. +traits that are not sealed. We are also free to change the signature of +`Sealed` in any way, as its items are not visible to downstream crates. Note that removing a public method or changing the signature of a public method in a sealed trait are still breaking changes.