serde: Add missing docs

ruma-serde/src/can_be_empty.rs

@@ -1,3 +1,8 @@
+//! Helpers for emptiness checks in `#[serde(skip_serializing_if)]`.
+
+/// Trait for types that have an "empty" state.
+///
+/// If `Default` is implemented for `Self`, `Self::default().is_empty()` should always be `true`.
 pub trait CanBeEmpty {
     /// Check whether `self` is empty.
     fn is_empty(&self) -> bool;

ruma-serde/src/canonical_json/value.rs

@@ -13,6 +13,7 @@ use super::Error;
 /// The inner type of `CanonicalJsonValue::Object`.
 pub type Object = BTreeMap<String, CanonicalJsonValue>;
 
+/// Represents a canonical JSON value as per the Matrix specification.
 #[derive(Clone, Eq, PartialEq)]
 pub enum CanonicalJsonValue {
     /// Represents a JSON null value.

ruma-serde/src/cow.rs

@@ -2,6 +2,13 @@ use std::{borrow::Cow, str};
 
 use serde::de::{self, Deserializer, Unexpected, Visitor};
 
+/// Deserialize a `Cow<'de, str>`.
+///
+/// Different from serde's implementation of `Deserialize` for `Cow` since it borrows from the
+/// input when possible.
+///
+/// This will become unnecessary if Rust gains lifetime specialization at some point; see
+/// <https://github.com/serde-rs/serde/issues/1497#issuecomment-716246686>.
 pub fn deserialize_cow_str<'de, D>(deserializer: D) -> Result<Cow<'de, str>, D::Error>
 where
     D: Deserializer<'de>,

ruma-serde/src/empty.rs

@@ -50,20 +50,24 @@ pub mod vec_as_map_of_empty {
 
     use super::Empty;
 
+    /// Serialize the given `Vec<T>` as a map of `T => Empty`.
     #[allow(clippy::ptr_arg)]
     pub fn serialize<S, T>(vec: &Vec<T>, serializer: S) -> Result<S::Ok, S::Error>
     where
         S: Serializer,
         T: Serialize + Eq + Ord,
     {
+        // FIXME: Don't construct a temporary `BTreeMap`.
         vec.iter().map(|v| (v, Empty {})).collect::<BTreeMap<_, _>>().serialize(serializer)
     }
 
+    /// Deserialize an object and return the keys as a `Vec<T>`.
     pub fn deserialize<'de, D, T>(deserializer: D) -> Result<Vec<T>, D::Error>
     where
         D: Deserializer<'de>,
         T: Deserialize<'de> + Eq + Ord,
     {
+        // FIXME: Don't construct a temporary `BTreeMap`.
         BTreeMap::<T, Empty>::deserialize(deserializer)
             .map(|hashmap| hashmap.into_iter().map(|(k, _)| k).collect())
     }

ruma-serde/src/json_string.rs

@@ -6,15 +6,17 @@ use serde::{
     ser::{Error as _, Serialize, Serializer},
 };
 
-pub fn serialize<T, S>(filter: T, serializer: S) -> Result<S::Ok, S::Error>
+/// Serialize the given value as a JSON string.
+pub fn serialize<T, S>(value: T, serializer: S) -> Result<S::Ok, S::Error>
 where
     T: Serialize,
     S: Serializer,
 {
-    let json = serde_json::to_string(&filter).map_err(S::Error::custom)?;
+    let json = serde_json::to_string(&value).map_err(S::Error::custom)?;
     serializer.serialize_str(&json)
 }
 
+/// Read a string from the input and deserialize it as a `T`.
 pub fn deserialize<'de, T, D>(deserializer: D) -> Result<T, D::Error>
 where
     T: DeserializeOwned,

ruma-serde/src/lib.rs

@@ -2,6 +2,8 @@
 #![doc(html_logo_url = "https://www.ruma.io/images/logo.png")]
 //! (De)serialization helpers for other ruma crates.
 
+#![warn(missing_docs)]
+
 mod buf;
 pub mod can_be_empty;
 mod canonical_json;

ruma-serde/src/single_element_seq.rs

@@ -5,14 +5,16 @@ use serde::{
     ser::{Serialize, Serializer},
 };
 
-pub fn serialize<T, S>(element: &T, serializer: S) -> Result<S::Ok, S::Error>
+/// Serialize the given value as a list of just that value.
+pub fn serialize<T, S>(value: &T, serializer: S) -> Result<S::Ok, S::Error>
 where
     T: Serialize,
     S: Serializer,
 {
-    [element].serialize(serializer)
+    [value].serialize(serializer)
 }
 
+/// Deserialize a list of one item and return that item.
 pub fn deserialize<'de, T, D>(deserializer: D) -> Result<T, D::Error>
 where
     T: Deserialize<'de>,

ruma-serde/src/test.rs

@@ -4,6 +4,7 @@ use std::fmt::Debug;
 
 use serde::{de::DeserializeOwned, Serialize};
 
+/// Assert that serialization of `de` results in `se` and deserialization of `se` results in `de`.
 pub fn serde_json_eq<T>(de: T, se: serde_json::Value)
 where
     T: Clone + Debug + PartialEq + Serialize + DeserializeOwned,

ruma-serde/src/urlencoded/ser.rs

@@ -53,8 +53,10 @@ impl<'input, 'output, Target: 'output + UrlEncodedTarget> Serializer<'input, 'ou
 /// Errors returned during serializing to `application/x-www-form-urlencoded`.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub enum Error {
-    Custom(Cow<'static, str>),
+    /// UTF-8 validation failed.
     Utf8(str::Utf8Error),
+    /// Something else.
+    Custom(Cow<'static, str>),
 }
 
 impl fmt::Display for Error {