docs: Harmonize ruma modules descriptions

ruma-api-macros/src/lib.rs

@@ -1,7 +1,6 @@
 #![doc(html_favicon_url = "https://www.ruma.io/favicon.ico")]
 #![doc(html_logo_url = "https://www.ruma.io/images/logo.png")]
-//! Crate ruma-api-macros provides a procedural macro for easily generating
+//! A procedural macro for easily generating [ruma-api]-compatible endpoints.
-//! [ruma-api]-compatible endpoints.
 //!
 //! This crate should never be used directly; instead, use it through the
 //! re-exports in ruma-api. Also note that for technical reasons, the

ruma-api/src/lib.rs

@@ -1,8 +1,7 @@
 #![doc(html_favicon_url = "https://www.ruma.io/favicon.ico")]
 #![doc(html_logo_url = "https://www.ruma.io/images/logo.png")]
-//! Crate `ruma_api` contains core types used to define the requests and responses for each endpoint
+//! Core types used to define the requests and responses for each endpoint in the various
-//! in the various [Matrix](https://matrix.org) API specifications.
+//! [Matrix API specifications][apis].
-//! These types can be shared by client and server code for all Matrix APIs.
 //!
 //! When implementing a new Matrix API, each endpoint has a request type which implements
 //! `Endpoint`, and a response type connected via an associated type.
@@ -11,6 +10,8 @@
 //! input parameters for requests, and the structure of a successful response.
 //! Such types can then be used by client code to make requests, and by server code to fulfill
 //! those requests.
+//!
+//! [apis]: https://matrix.org/docs/spec/#matrix-apis
 
 #![doc(html_favicon_url = "https://www.ruma.io/favicon.ico")]
 #![warn(rust_2018_idioms)]
@@ -232,7 +233,7 @@ pub trait EndpointError: StdError + Sized + 'static {
     ) -> Result<Self, error::ResponseDeserializationError>;
 }
 
-/// A request type for a Matrix API endpoint. (trait used for sending requests)
+/// A request type for a Matrix API endpoint, used for sending requests.
 pub trait OutgoingRequest {
     /// A type capturing the expected error conditions the server can return.
     type EndpointError: EndpointError;
@@ -261,7 +262,7 @@ pub trait OutgoingRequest {
     ) -> Result<http::Request<Vec<u8>>, IntoHttpError>;
 }
 
-/// A request type for a Matrix API endpoint. (trait used for receiving requests)
+/// A request type for a Matrix API endpoint, used for receiving requests.
 pub trait IncomingRequest: Sized {
     /// A type capturing the error conditions that can be returned in the response.
     type EndpointError: EndpointError;
@@ -276,10 +277,10 @@ pub trait IncomingRequest: Sized {
     fn try_from_http_request(req: http::Request<Vec<u8>>) -> Result<Self, FromHttpRequestError>;
 }
 
-/// Marker trait for requests that don't require authentication. (for the client side)
+/// Marker trait for requests that don't require authentication, for the client side.
 pub trait OutgoingNonAuthRequest: OutgoingRequest {}
 
-/// Marker trait for requests that don't require authentication. (for the server side)
+/// Marker trait for requests that don't require authentication, for the server side.
 pub trait IncomingNonAuthRequest: IncomingRequest {}
 
 /// Authentication scheme used by the endpoint.

ruma-appservice-api/src/lib.rs

@@ -1,8 +1,9 @@
 #![doc(html_favicon_url = "https://www.ruma.io/favicon.ico")]
 #![doc(html_logo_url = "https://www.ruma.io/images/logo.png")]
-//! Crate ruma_appservice_api contains serializable types for the requests and responses for each
+//! (De)serializable types for the [Matrix Application Service API][appservice-api].
-//! endpoint in the [Matrix](https://matrix.org/) application service API specification. These
+//! These types can be shared by application service and server code.
-//! types can be shared by application service and server code.
+//!
+//! [appservice-api]: https://matrix.org/docs/spec/application_service/r0.1.2.html
 
 #![warn(missing_debug_implementations, missing_docs)]
 

ruma-client-api/src/lib.rs

@@ -1,8 +1,9 @@
 #![doc(html_favicon_url = "https://www.ruma.io/favicon.ico")]
 #![doc(html_logo_url = "https://www.ruma.io/images/logo.png")]
-//! Crate ruma_client_api contains serializable types for the requests and responses for each
+//! (De)serializable types for the [Matrix Client-Server API][client-api].
-//! endpoint in the [Matrix](https://matrix.org/) client API specification. These types can be
+//! These types can be shared by client and server code.
-//! shared by client and server code.
+//!
+//! [client-api]: https://matrix.org/docs/spec/client_server/r0.6.1.html
 
 #![warn(missing_debug_implementations, missing_docs)]
 

ruma-client/src/lib.rs

@@ -1,6 +1,6 @@
 #![doc(html_favicon_url = "https://www.ruma.io/favicon.ico")]
 #![doc(html_logo_url = "https://www.ruma.io/images/logo.png")]
-//! Crate `ruma_client` is a [Matrix](https://matrix.org/) client library.
+//! A [Matrix](https://matrix.org/) client library.
 //!
 //! # Usage
 //!

ruma-events-macros/src/lib.rs

@@ -1,7 +1,6 @@
 #![doc(html_favicon_url = "https://www.ruma.io/favicon.ico")]
 #![doc(html_logo_url = "https://www.ruma.io/images/logo.png")]
-//! Crate `ruma_events_macros` provides a procedural macro for generating
+//! A procedural macro for generating [ruma-events] events.
-//! [ruma-events] events.
 //!
 //! See the documentation for the individual macros for usage details.
 //!

ruma-events/src/lib.rs

@@ -1,7 +1,7 @@
 #![doc(html_favicon_url = "https://www.ruma.io/favicon.ico")]
 #![doc(html_logo_url = "https://www.ruma.io/images/logo.png")]
-//! Crate `ruma_events` contains serializable types for the events in the
+//! (De)serializable types for the events in the [Matrix](https://matrix.org) specification.
-//! [Matrix](https://matrix.org) specification that can be shared by client and server code.
+//! These types are used by other ruma crates.
 //!
 //! All data exchanged over Matrix is expressed as an event.
 //! Different event types represent different actions, such as joining a room or sending a message.

ruma-federation-api/src/lib.rs

@@ -1,6 +1,9 @@
 #![doc(html_favicon_url = "https://www.ruma.io/favicon.ico")]
 #![doc(html_logo_url = "https://www.ruma.io/images/logo.png")]
-//! (De)serializable types for the Matrix Federation API.
+//! (De)serializable types for the [Matrix Server-Server API][federation-api].
+//! These types are used by server code.
+//!
+//! [federation-api]: https://matrix.org/docs/spec/server_server/r0.1.4.html
 
 #![warn(missing_docs)]
 

ruma-identifiers/src/lib.rs

@@ -1,7 +1,7 @@
 #![doc(html_favicon_url = "https://www.ruma.io/favicon.ico")]
 #![doc(html_logo_url = "https://www.ruma.io/images/logo.png")]
-//! Crate **ruma_identifiers** contains types for [Matrix](https://matrix.org/) identifiers
+//! Types for [Matrix](https://matrix.org/) identifiers for devices, events, keys, rooms, servers,
-//! for events, rooms, room aliases, room versions, and users.
+//! users and URIs.
 
 #![warn(rust_2018_idioms, missing_debug_implementations, missing_docs)]
 #![cfg_attr(docsrs, feature(doc_cfg))]

ruma-identity-service-api/src/lib.rs

@@ -1,6 +1,9 @@
 #![doc(html_favicon_url = "https://www.ruma.io/favicon.ico")]
 #![doc(html_logo_url = "https://www.ruma.io/images/logo.png")]
-//! (De)serializable types for the Matrix Identity Service API.
+//! (De)serializable types for the [Matrix Identity Service API][identity-api].
+//! These types can be shared by client and identity service code.
+//!
+//! [identity-api]: https://matrix.org/docs/spec/identity_service/r0.3.0.html
 
 #![warn(missing_docs)]
 

ruma-push-gateway-api/src/lib.rs

@@ -1,6 +1,9 @@
 #![doc(html_favicon_url = "https://www.ruma.io/favicon.ico")]
 #![doc(html_logo_url = "https://www.ruma.io/images/logo.png")]
-//! (De)serializable types for the Matrix Push Gateway API.
+//! (De)serializable types for the [Matrix Push Gateway API][push-api].
+//! These types can be shared by push gateway and server code.
+//!
+//! [push-api]: https://matrix.org/docs/spec/push_gateway/r0.1.1.html
 
 #![warn(missing_docs)]
 

ruma-serde/src/lib.rs

@@ -1,6 +1,6 @@
 #![doc(html_favicon_url = "https://www.ruma.io/favicon.ico")]
 #![doc(html_logo_url = "https://www.ruma.io/images/logo.png")]
-//! De-/serialization helpers for other ruma crates
+//! (De)serialization helpers for other ruma crates.
 
 pub mod can_be_empty;
 mod canonical_json;
@@ -48,10 +48,12 @@ pub fn is_true(b: &bool) -> bool {
     *b
 }
 
-/// A type that can be sent to another party that understands the matrix protocol. If any of the
+/// A type that can be sent to another party that understands the matrix protocol.
-/// fields of `Self` don't implement serde's `Deserialize`, you can derive this trait to generate a
+///
-/// corresponding 'Incoming' type that supports deserialization. This is useful for things like
+/// If any of the fields of `Self` don't implement serde's `Deserialize`, you can derive this trait
-/// ruma_events' `EventResult` type. For more details, see the [derive macro's documentation][doc].
+/// to generate a corresponding 'Incoming' type that supports deserialization. This is useful for
+/// things like 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

ruma-signatures/src/lib.rs

@@ -1,7 +1,6 @@
 #![doc(html_favicon_url = "https://www.ruma.io/favicon.ico")]
 #![doc(html_logo_url = "https://www.ruma.io/images/logo.png")]
-//! Crate `ruma_signatures` implements digital signatures according to the
+//! Digital signatures according to the [Matrix](https://matrix.org/) specification.
-//! [Matrix](https://matrix.org/) specification.
 //!
 //! Digital signatures are used by Matrix homeservers to verify the authenticity of events in the
 //! Matrix system, as well as requests between homeservers for federation. Each homeserver has one