1 files changed, 188 insertions, 0 deletions
diff --git a/third_party/rust/derive_more-impl/doc/from.md b/third_party/rust/derive_more-impl/doc/from.md
new file mode 100644
index 0000000000..1bc0cb4de3
--- /dev/null
+++ b/third_party/rust/derive_more-impl/doc/from.md
@@ -0,0 +1,188 @@
+# What `#[derive(From)]` generates
+
+The point of deriving this type is that it makes it easy to create a new
+instance of the type by using the `.into()` method on the value(s) that it
+should contain. This is done by implementing the `From` trait for the type
+that is passed to the derive.
+
+
+
+
+## Structs
+
+For structs with a single field you can call `.into()` on the desired content
+itself after deriving `From`.
+
+```rust
+# use derive_more::From;
+#
+#[derive(Debug, From, PartialEq)]
+struct Int(i32);
+
+assert_eq!(Int(2), 2.into());
+```
+
+For structs that have multiple fields `.into()` needs to be called on a tuple
+containing the desired content for each field.
+
+```rust
+# use derive_more::From;
+#
+#[derive(Debug, From, PartialEq)]
+struct Point(i32, i32);
+
+assert_eq!(Point(1, 2), (1, 2).into());
+```
+
+To specify concrete types to derive convert from use `#[from(<types>)]`.
+
+```rust
+# use std::borrow::Cow;
+#
+# use derive_more::From;
+#
+#[derive(Debug, From, PartialEq)]
+#[from(Cow<'static, str>, String, &'static str)]
+struct Str(Cow<'static, str>);
+
+assert_eq!(Str("&str".into()), "&str".into());
+assert_eq!(Str("String".into()), "String".to_owned().into());
+assert_eq!(Str("Cow".into()), Cow::Borrowed("Cow").to_owned().into());
+
+#[derive(Debug, From, PartialEq)]
+#[from((i16, i16), (i32, i32))]
+struct Point {
+    x: i32,
+    y: i32,
+}
+
+assert_eq!(Point { x: 1_i32, y: 2_i32 }, (1_i16, 2_i16).into());
+assert_eq!(Point { x: 3_i32, y: 4_i32 }, (3_i32, 4_i32).into());
+```
+
+Also, you can forward implementation to the inner type, which means deriving `From` for any type, that derives `From`
+inner type.
+
+```rust
+# use std::borrow::Cow;
+#
+# use derive_more::From;
+#
+#[derive(Debug, From, PartialEq)]
+#[from(forward)]
+struct Str {
+    inner: Cow<'static, str>,
+}
+
+assert_eq!(Str { inner: "&str".into() }, "&str".into());
+assert_eq!(Str { inner: "String".into() }, "String".to_owned().into());
+assert_eq!(Str { inner: "Cow".into() }, Cow::Borrowed("Cow").to_owned().into());
+```
+
+
+
+
+## Enums
+
+For enums `.into()` works for each variant as if they were structs. This
+includes specifying concrete types via `#[from(<types>)]` or forwarding
+implementation with `#[from(forward)]`.
+
+```rust
+# use derive_more::From;
+#
+#[derive(Debug, From, PartialEq)]
+enum IntOrPoint {
+    Int(i32),
+    Point {
+        x: i32,
+        y: i32,
+    },
+}
+
+assert_eq!(IntOrPoint::Int(1), 1.into());
+assert_eq!(IntOrPoint::Point { x: 1, y: 2 }, (1, 2).into());
+```
+
+By default, `From` is generated for every enum variant, but you can skip some
+variants via `#[from(skip)]` or only concrete fields via `#[from]`.
+
+```rust
+# mod from {
+# use derive_more::From;
+#[derive(Debug, From, PartialEq)]
+enum Int {
+    #[from]
+    Derived(i32),
+    NotDerived(i32),
+}
+# }
+
+// Is equivalent to:
+
+# mod skip {
+# use derive_more::From;
+#[derive(Debug, From, PartialEq)]
+enum Int {
+    Derived(i32),
+    #[from(skip)]
+    NotDerived(i32),
+}
+# }
+```
+
+
+
+
+## Example usage
+
+```rust
+# use derive_more::From;
+#
+// Allow converting from i32
+#[derive(From, PartialEq)]
+struct MyInt(i32);
+
+// Forward from call to the field, so allow converting
+// from anything that can be converted into an i64 (so most integers)
+#[derive(From, PartialEq)]
+#[from(forward)]
+struct MyInt64(i64);
+
+// You can ignore a variant
+#[derive(From, PartialEq)]
+enum MyEnum {
+    SmallInt(i32),
+    NamedBigInt { int: i64 },
+    #[from(ignore)]
+    NoFromImpl(i64),
+}
+
+// Or explicitly annotate the ones you need
+#[derive(From, PartialEq)]
+enum MyEnum2 {
+    #[from]
+    SmallInt(i32),
+    #[from]
+    NamedBigInt { int: i64 },
+    NoFromImpl(i64),
+}
+
+// And even specify additional conversions for them
+#[derive(From, PartialEq)]
+enum MyEnum3 {
+    #[from(i8, i32)]
+    SmallInt(i32),
+    #[from(i16, i64)]
+    NamedBigInt { int: i64 },
+    NoFromImpl(i64),
+}
+
+assert!(MyInt(2) == 2.into());
+assert!(MyInt64(6) == 6u8.into());
+assert!(MyEnum::SmallInt(123) == 123i32.into());
+assert!(MyEnum::SmallInt(123) != 123i64.into());
+assert!(MyEnum::NamedBigInt{int: 123} == 123i64.into());
+assert!(MyEnum3::SmallInt(123) == 123i8.into());
+assert!(MyEnum3::NamedBigInt{int: 123} == 123i16.into());
+```