Add reasons for each doctest ignore

crates/ruma-client/src/lib.rs

@@ -9,6 +9,7 @@
 //! provided for the client (feature `client-api`):
 //!
 //! ```ignore
+//! # // HACK: "ignore" the doctest here because client.log_in needs client-api feature.
 //! // type MatrixClient = ruma_client::Client<ruma_client::http_client::_>;
 //! # type MatrixClient = ruma_client::Client<ruma_client::http_client::Dummy>;
 //! # let work = async {
@@ -89,6 +90,7 @@ extern crate hyper_rustls_crate as hyper_rustls;
 extern crate isahc_crate as isahc;
 
 #[cfg(feature = "client-api")]
+#[cfg_attr(docsrs, doc(cfg(feature = "client")))]
 mod client_api;
 mod error;
 pub mod http_client;

crates/ruma-events-macros/src/lib.rs

@@ -31,16 +31,20 @@ mod event_parse;
 /// # Examples
 ///
 /// ```ignore
+/// # // HACK: This is "ignore" because of cyclical dependency drama.
 /// use ruma_events_macros::event_enum;
 ///
 /// event_enum! {
-///     name: AnyBarEvent, // `BarEvent` has to be a valid type at `::ruma_events::BarEvent`
+///     kind: ToDevice,
 ///     events: [
 ///         "m.any.event",
 ///         "m.other.event",
 ///     ]
 /// }
 /// ```
+/// (The argument to `kind` has to be a valid identifier for `<EventKind as Parse>::parse`)
+//// TODO: Change above (`<EventKind as Parse>::parse`) to [] after fully qualified syntax is
+//// supported:  https://github.com/rust-lang/rust/issues/74563
 #[proc_macro]
 pub fn event_enum(input: TokenStream) -> TokenStream {
     let event_enum_input = syn::parse_macro_input!(input as EventEnumInput);

crates/ruma-serde-macros/src/lib.rs

@@ -31,6 +31,7 @@ mod util;
 /// of the struct, this simple implementation will be generated:
 ///
 /// ```ignore
+/// # // TODO: "ignore" this doctest until it is more extensively documented. (See #541)
 /// impl Outgoing for MyType {
 ///     type Incoming = Self;
 /// }

crates/ruma-serde/src/raw.rs

@@ -22,7 +22,12 @@ use crate::cow::MyCowStr;
 /// All event structs and enums implement `Serialize` / `Deserialize`, `Raw` should be used
 /// to pass around events in a lossless way.
 ///
-/// ```ignore
+/// ```no_run
+/// # use serde::Deserialize;
+/// # use ruma_serde::Raw;
+/// # #[derive(Deserialize)]
+/// # struct AnyRoomEvent;
+///
 /// let json = r#"{ "type": "imagine a full event", "content": {...} }"#;
 ///
 /// let deser = serde_json::from_str::<Raw<AnyRoomEvent>>(json)