appservice: Improve docs

matrix_sdk/src/client.rs

@@ -474,9 +474,11 @@ impl RequestConfig {
         self
     }
 
-    /// [Assert the identity][identity-assertion] of requests to the `user_id` in the `Session`
+    /// All outgoing http requests will have a GET query key-value appended with `user_id` being
+    /// the key and the `user_id` from the `Session` being the value. Will error if there's no
+    /// `Session`. This is called [identity assertion] in the Matrix Appservice Spec
     ///
-    /// [identity-assertion]: https://spec.matrix.org/unstable/application-service-api/#identity-assertion
+    /// [identity assertion]: https://spec.matrix.org/unstable/application-service-api/#identity-assertion
     #[cfg(feature = "appservice")]
     #[cfg_attr(feature = "docs", doc(cfg(appservice)))]
     pub fn assert_identity(mut self) -> Self {

matrix_sdk/src/lib.rs

@@ -47,6 +47,8 @@
 //! * `require_auth_for_profile_requests`: Whether to send the access token in the authentication
 //! header when calling endpoints that retrieve profile data. This matches the synapse
 //! configuration `require_auth_for_profile_requests`. Enabled by default.
+//! * `appservice`: Enables low-level appservice functionality. For an high-level API there's the
+//! `matrix-sdk-appservice` crate
 
 #![deny(
     missing_debug_implementations,

matrix_sdk_appservice/src/lib.rs

@@ -14,18 +14,24 @@
 
 //! Matrix [Application Service] library
 //!
+//! The appservice crate aims to provide a batteries-included experience. That means that we
+//! * ship with functionality to configure your webserver crate or simply run the webserver for you
+//! * receive and validate requests from the homeserver correctly
+//! * allow calling the homeserver with proper virtual user identity assertion
+//! * have the goal to have a consistent room state available by leveraging the stores that the matrix-sdk provides
+//!
 //! # Quickstart
 //!
 //! ```no_run
 //! # async {
 //! use matrix_sdk_appservice::{Appservice, AppserviceRegistration};
 //!
-//! let homeserver_url = "http://localhost:8008";
+//! let homeserver_url = "http://127.0.0.1:8008";
 //! let server_name = "localhost";
 //! let registration = AppserviceRegistration::try_from_yaml_str(
 //!     r"
 //!         id: appservice
-//!         url: http://localhost:9009
+//!         url: http://127.0.0.1:9009
 //!         as_token: as_token
 //!         hs_token: hs_token
 //!         sender_localpart: _appservice
@@ -37,6 +43,7 @@
 //!     .unwrap();
 //!
 //! let appservice = Appservice::new(homeserver_url, server_name, registration).await.unwrap();
+//! // set event handler with `appservice.client().set_event_handler()` here
 //! let (host, port) = appservice.get_host_and_port_from_registration().unwrap();
 //! appservice.run(host, port).await.unwrap();
 //! # };
@@ -91,6 +98,8 @@ pub struct AppserviceRegistration {
 
 impl AppserviceRegistration {
     /// Try to load registration from yaml string
+    ///
+    /// See the fields of [`Registration`] for the required format
     pub fn try_from_yaml_str(value: impl AsRef<str>) -> Result<Self> {
         Ok(Self {
             inner: serde_yaml::from_str(value.as_ref())?,
@@ -98,6 +107,8 @@ impl AppserviceRegistration {
     }
 
     /// Try to load registration from yaml file
+    ///
+    /// See the fields of [`Registration`] for the required format
     pub fn try_from_yaml_file(path: impl Into<PathBuf>) -> Result<Self> {
         let file = File::open(path.into())?;
 
@@ -159,6 +170,14 @@ pub struct Appservice {
 
 impl Appservice {
     /// Create new Appservice
+    ///
+    /// # Arguments
+    ///
+    /// * `homeserver_url` - The homeserver that the client should connect to.
+    /// * `server_name` - The server name to use when constructing user ids from the localpart.
+    /// * `registration` - The [Appservice Registration] to use when interacting with the homserver.
+    ///
+    /// [Appservice Registration]: https://matrix.org/docs/spec/application_service/r0.1.2#registration
     pub async fn new(
         homeserver_url: impl TryInto<Url, Error = url::ParseError>,
         server_name: impl TryInto<ServerNameBox, Error = identifiers::Error>,
@@ -248,6 +267,8 @@ impl Appservice {
     }
 
     /// Compare the given `hs_token` against `registration.hs_token`
+    ///
+    /// Returns `true` if the tokens match, `false` otherwise.
     pub fn verify_hs_token(&self, hs_token: impl AsRef<str>) -> bool {
         self.registration.hs_token == hs_token.as_ref()
     }
@@ -265,7 +286,7 @@ impl Appservice {
         Ok(false)
     }
 
-    /// Get host and port from registration url
+    /// Get the host and port from the registration URL
     ///
     /// If no port is found it falls back to scheme defaults: 80 for http and 443 for https
     pub fn get_host_and_port_from_registration(&self) -> Result<(Host, Port)> {