Incorporate feedback by lu-fennell, Nauxuron

ruma-api-macros/src/api/request.rs

@@ -75,6 +75,7 @@ impl Request {
     pub fn has_header_fields(&self) -> bool {
         self.fields.iter().any(|field| field.is_header())
     }
+
     /// Whether or not this request has any data in the URL path.
     pub fn has_path_fields(&self) -> bool {
         self.fields.iter().any(|field| field.is_path())

ruma-api-macros/src/derive_outgoing.rs

@@ -32,7 +32,7 @@ pub fn expand_derive_outgoing(input: DeriveInput) -> syn::Result<TokenStream> {
         Data::Struct(s) => match s.fields {
             Fields::Named(fs) => fs.named.into_pairs().map(Pair::into_value).collect(),
             Fields::Unnamed(fs) => fs.unnamed.into_pairs().map(Pair::into_value).collect(),
-            Fields::Unit => return Ok(impl_send_recv_incoming_self(input.ident)),
+            Fields::Unit => return Ok(impl_outgoing_with_incoming_self(input.ident)),
         },
     };
 
@@ -68,7 +68,7 @@ pub fn expand_derive_outgoing(input: DeriveInput) -> syn::Result<TokenStream> {
     }
 
     if !any_attribute {
-        return Ok(impl_send_recv_incoming_self(input.ident));
+        return Ok(impl_outgoing_with_incoming_self(input.ident));
     }
 
     let vis = input.vis;
@@ -104,7 +104,7 @@ fn no_deserialize_in_attrs(attrs: &[Attribute]) -> bool {
     false
 }
 
-fn impl_send_recv_incoming_self(ident: Ident) -> TokenStream {
+fn impl_outgoing_with_incoming_self(ident: Ident) -> TokenStream {
     quote! {
         impl ruma_api::Outgoing for #ident {
             type Incoming = Self;

ruma-api-macros/src/lib.rs

@@ -73,8 +73,10 @@ pub fn ruma_api(input: TokenStream) -> TokenStream {
 ///     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))]
-pub fn derive_send_recv(input: TokenStream) -> TokenStream {
+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()
 }

src/lib.rs

@@ -200,11 +200,12 @@ use serde_urlencoded;
 ///
 /// ## Fallible deserialization
 ///
-/// All request and response types also derive `ruma_api::Outgoing`. As such, to allow fallible
+/// All request and response types also derive [`Outgoing`][]. As such, to allow fallible
 /// deserialization, you can use the `#[wrap_incoming]` attribute. For details, see the
 /// documentation for [`Outgoing`][].
 ///
 /// [`Outgoing`]: derive.Outgoing.html
+// TODO: Explain the concept of fallible deserialization before jumping to `ruma_api::Outgoing`
 #[cfg(feature = "with-ruma-api-macros")]
 pub use ruma_api_macros::ruma_api;
 
@@ -230,6 +231,7 @@ pub mod exports {
 /// ruma_events' `EventResult` type. For more details, see the [derive macro's documentation][doc].
 ///
 /// [doc]: derive.Outgoing.html
+// TODO: Better explain how this trait relates to serde's traits
 pub trait Outgoing {
     /// The 'Incoming' variant of `Self`.
     type Incoming;