chris/ruwuma
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Fix outdated docs on Outgoing derive

Browse Source
This commit is contained in:
Jonas Platte 2020-08-17 21:17:09 +02:00
parent e06c800701
commit 4a52931af7
No known key found for this signature in database
GPG Key ID: CC154DE0E30B7C67
1 changed files with 35 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

68
ruma-api-macros/src/lib.rs
View File

@ -36,45 +36,47 @@ pub fn ruma_api(input: TokenStream) -> TokenStream {
}
/// Derive the `Outgoing` trait, possibly generating an 'Incoming' version of the struct this
/// derive macro is used on. Specifically, if no `#[wrap_incoming]` attribute is used on any of the
/// fields of the struct, this simple implementation will be generated:
/// derive macro is used on. Specifically, if no lifetime variables are used on any of the fields
/// of the struct, this simple implementation will be generated:
///
/// ```ignore
/// impl Outgoing for MyType {
/// type Incoming = Self;
/// }
/// ```
///
/// If, however, `#[wrap_incoming]` is used (which is the only reason you should ever use this
/// derive macro manually), a new struct `IncomingT` (where `T` is the type this derive is used on)
/// is generated, with all of the fields with `#[wrap_incoming]` replaced:
///
/// ```ignore
/// #[derive(Outgoing)]
/// struct MyType {
/// pub foo: Foo,
/// #[wrap_incoming]
/// pub bar: Bar,
/// #[wrap_incoming(Baz)]
/// pub baz: Option<Baz>,
/// #[wrap_incoming(with EventResult)]
/// pub x: XEvent,
/// #[wrap_incoming(YEvent with EventResult)]
/// pub ys: Vec<YEvent>,
/// }
///
/// // generated
/// struct IncomingMyType {
/// pub foo: Foo,
/// pub bar: IncomingBar,
/// pub baz: Option<IncomingBaz>,
/// pub x: EventResult<XEvent>,
/// pub ys: Vec<EventResult<YEvent>>,
/// }
/// ```
// TODO: Make it clear that `#[wrap_incoming]` and `#[wrap_incoming(Type)]` without the "with" part
// are (only) useful for fallible deserialization of nested structures.
#[proc_macro_derive(Outgoing, attributes(wrap_incoming, incoming_no_deserialize))]
/* TODO: Extend docs. Previously:
If, however, `#[wrap_incoming]` is used (which is the only reason you should ever use this
derive macro manually), a new struct `IncomingT` (where `T` is the type this derive is used on)
is generated, with all of the fields with `#[wrap_incoming]` replaced:
```ignore
#[derive(Outgoing)]
struct MyType {
pub foo: Foo,
#[wrap_incoming]
pub bar: Bar,
#[wrap_incoming(Baz)]
pub baz: Option<Baz>,
#[wrap_incoming(with EventResult)]
pub x: XEvent,
#[wrap_incoming(YEvent with EventResult)]
pub ys: Vec<YEvent>,
}
// generated
struct IncomingMyType {
pub foo: Foo,
pub bar: IncomingBar,
pub baz: Option<IncomingBaz>,
pub x: EventResult<XEvent>,
pub ys: Vec<EventResult<YEvent>>,
}
```
*/
#[proc_macro_derive(Outgoing, attributes(incoming_no_deserialize))]
pub fn derive_outgoing(input: TokenStream) -> TokenStream {
let input = parse_macro_input!(input as DeriveInput);
expand_derive_outgoing(input).unwrap_or_else(|err| err.to_compile_error()).into()