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

docs: Harmonize ruma modules descriptions

Browse Source
This commit is contained in:
Kévin Commaille 2021-04-07 12:14:49 +02:00
parent b3bbd31fa3
commit 963400979b
No known key found for this signature in database
GPG Key ID: 483BCF4C5AF1E1E5
13 changed files with 43 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -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
//! [ruma-api]-compatible endpoints.
//! A procedural macro for easily generating [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

15
ruma-api/src/lib.rs
View File

@ -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
//! in the various [Matrix](https://matrix.org) API specifications.
//! These types can be shared by client and server code for all Matrix APIs.
//! Core types used to define the requests and responses for each endpoint in the various
//! [Matrix API specifications][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.

7
ruma-appservice-api/src/lib.rs
View File

@ -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
//! endpoint in the [Matrix](https://matrix.org/) application service API specification. These
//! types can be shared by application service and server code.
//! (De)serializable types for the [Matrix Application Service API][appservice-api].
//! These 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)]

7
ruma-client-api/src/lib.rs
View File

@ -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
//! endpoint in the [Matrix](https://matrix.org/) client API specification. These types can be
//! shared by client and server code.
//! (De)serializable types for the [Matrix Client-Server API][client-api].
//! These types can be 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)]

2
ruma-client/src/lib.rs
View File

@ -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
//!

3
ruma-events-macros/src/lib.rs
View File

@ -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
//! [ruma-events] events.
//! A procedural macro for generating [ruma-events] events.
//!
//! See the documentation for the individual macros for usage details.
//!

4
ruma-events/src/lib.rs
View File

@ -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
//! [Matrix](https://matrix.org) specification that can be shared by client and server code.
//! (De)serializable types for the events in the [Matrix](https://matrix.org) specification.
//! 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.

5
ruma-federation-api/src/lib.rs
View File

@ -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)]

4
ruma-identifiers/src/lib.rs
View File

@ -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
//! for events, rooms, room aliases, room versions, and users.
//! Types for [Matrix](https://matrix.org/) identifiers for devices, events, keys, rooms, servers,
//! users and URIs.
#![warn(rust_2018_idioms, missing_debug_implementations, missing_docs)]
#![cfg_attr(docsrs, feature(doc_cfg))]

5
ruma-identity-service-api/src/lib.rs
View File

@ -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)]

5
ruma-push-gateway-api/src/lib.rs
View File

@ -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)]

12
ruma-serde/src/lib.rs
View File

@ -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
/// 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
/// ruma_events' `EventResult` type. For more details, see the [derive macro's documentation][doc].
/// A type that can be sent to another party that understands the matrix protocol.
///
/// If any of the 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 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

3
ruma-signatures/src/lib.rs
View File

@ -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
//! [Matrix](https://matrix.org/) specification.
//! Digital signatures according to the [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