Skip to content

Improve documentation on derived trait bounds #40

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
stevenengler wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Improve documentation on derived trait bounds #40

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 32 additions & 16 deletions src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -179,7 +179,8 @@ enum Enum<T> {

###### Generic Parameters Bound to the `Debug` Trait or Others

Generic parameters will be automatically bound to the `Debug` trait if necessary.
Unlike the trait derives provided by the standard library,
the types associated with each field or enum variant will be automatically bound to the `Debug` trait if necessary.

```rust
# #[cfg(feature = "Debug")]
Expand All @@ -194,12 +195,14 @@ enum Enum<T, K> {
f1: K,
},
V3(
T
Option<T>,
),
}
# }
```

Here the derived bounds are `K: Debug, Option<T>: Debug`.

Or you can set the where predicates by yourself.

```rust
Expand All @@ -214,21 +217,21 @@ fn fmt<D>(_s: &D, f: &mut Formatter<'_>) -> fmt::Result {
}

#[derive(Educe)]
#[educe(Debug(bound(T: std::fmt::Debug)))]
#[educe(Debug(bound(Option<T>: std::fmt::Debug)))]
enum Enum<T, K> {
V1,
V2 {
#[educe(Debug(method(fmt)))]
f1: K,
},
V3(
T
Option<T>,
),
}
# }
```

In the above case, `T` is bound to the `Debug` trait, but `K` is not.
In the above case, `Option<T>` is bound to the `Debug` trait, but `K` is not.

Or, you can have `educe` replicate the behaviour of `std`'s `derive`'s, where a bound is produced for *every* generic parameter, without regard to how it's used in the structure:

Expand All @@ -239,14 +242,17 @@ use educe::Educe;

#[derive(Educe)]
#[educe(Debug(bound(*)))]
struct Struct<T> {
struct Struct<T, V> {
#[educe(Debug(ignore))]
f: T,
g: Option<V>,
}
# }
```

This can be useful if you don't want to make the trait implementation part of your permanent public API. In this example, `Struct<T>` doesn't implement `Debug` unless `T` does. I.e., it has a `T: Debug` bound even though that's not needed right now. Later we might want to display `f`; we wouldn't then need to make a breaking API change by adding the bound.
Here the derived bounds are `T: Debug, V: Debug`.

This can be useful if you don't want to make the trait implementation part of your permanent public API. In this example, `Struct<T>` doesn't implement `Debug` unless `T` does. I.e., it has a `T: Debug` bound even though that's not needed right now. Later we might want to display `f`; we wouldn't then need to make a breaking API change by adding the bound. We can also change the type of `g` without affecting the `V: Debug` bound.

This was the behaviour of `Trait(bound)` in educe 0.4.x and earlier.

Expand Down Expand Up @@ -336,7 +342,9 @@ enum Enum<T: A> {

###### Generic Parameters Bound to the `Clone` Trait or Others

Generic parameters will be automatically bound to the `Clone` trait if necessary. If the `#[educe(Copy)]` attribute exists, they will be bound to the `Copy` trait.
Unlike the trait derives provided by the standard library,
the types associated with each field or enum variant will be automatically bound to the `Clone` trait if necessary.
If the `#[educe(Copy)]` attribute exists, they will be bound to the `Copy` trait.

```rust
# #[cfg(feature = "Clone")]
Expand Down Expand Up @@ -448,7 +456,8 @@ enum Enum {

###### Generic Parameters Bound to the `Copy` Trait or Others

All generic parameters will be automatically bound to the `Copy` trait.
Unlike the trait derives provided by the standard library,
the types associated with each field or enum variant will be automatically bound to the `Copy` trait.

```rust
# #[cfg(all(feature = "Clone", feature = "Copy"))]
Expand Down Expand Up @@ -618,7 +627,8 @@ enum Enum<T: A> {

###### Generic Parameters Bound to the `PartialEq` Trait or Others

Generic parameters will be automatically bound to the `PartialEq` trait if necessary.
Unlike the trait derives provided by the standard library,
the types associated with each field or enum variant will be automatically bound to the `PartialEq` trait if necessary.

```rust
# #[cfg(feature = "PartialEq")]
Expand Down Expand Up @@ -805,7 +815,8 @@ enum Enum<T: A> {

###### Generic Parameters Bound to the `PartialEq` Trait or Others

Generic parameters will be automatically bound to the `PartialEq` trait if necessary.
Unlike the trait derives provided by the standard library,
the types associated with each field or enum variant will be automatically bound to the `PartialEq` trait if necessary.

```rust
# #[cfg(all(feature = "PartialEq", feature = "Eq"))]
Expand Down Expand Up @@ -1020,7 +1031,8 @@ enum Enum {

###### Generic Parameters Bound to the `PartialOrd` Trait or Others

Generic parameters will be automatically bound to the `PartialOrd` trait if necessary.
Unlike the trait derives provided by the standard library,
the types associated with each field or enum variant will be automatically bound to the `PartialOrd` trait if necessary.

```rust
# #[cfg(feature = "PartialOrd")]
Expand Down Expand Up @@ -1255,7 +1267,8 @@ enum Enum {

###### Generic Parameters Bound to the `Ord` Trait or Others

Generic parameters will be automatically bound to the `Ord` trait if necessary.
Unlike the trait derives provided by the standard library,
the types associated with each field or enum variant will be automatically bound to the `Ord` trait if necessary.

```rust
# #[cfg(all(feature = "PartialOrd", feature = "Ord"))]
Expand Down Expand Up @@ -1406,7 +1419,8 @@ enum Enum<T> {

###### Generic Parameters Bound to the `Hash` Trait or Others

Generic parameters will be automatically bound to the `Hash` trait if necessary.
Unlike the trait derives provided by the standard library,
the types associated with each field or enum variant will be automatically bound to the `Hash` trait if necessary.

```rust
# #[cfg(feature = "Hash")]
Expand Down Expand Up @@ -1634,7 +1648,8 @@ union Union {

###### Generic Parameters Bound to the `Default` Trait or Others

Generic parameters will be automatically bound to the `Default` trait if necessary.
Unlike the trait derives provided by the standard library,
the types associated with each field or enum variant will be automatically bound to the `Default` trait if necessary.

```rust
# #[cfg(feature = "Default")]
Expand Down Expand Up @@ -1842,7 +1857,8 @@ enum Enum {

###### Generic Parameters Bound to the `Into` Trait or Others

Generic parameters will be automatically bound to the `Into<type>` trait if necessary.
Unlike the trait derives provided by the standard library,
the types associated with each field or enum variant will be automatically bound to the `Into<type>` trait if necessary.

```rust
# #[cfg(feature = "Into")]
Expand Down