From b616ba82334c889b2a564e2217075a9ca8a2cb69 Mon Sep 17 00:00:00 2001
From: Jonathan de Jong <jonathandejong02@gmail.com>
Date: Fri, 14 May 2021 11:44:49 +0000
Subject: [PATCH] Add reasons for each doctest ignore

---
 crates/ruma-client/src/lib.rs        | 2 ++
 crates/ruma-events-macros/src/lib.rs | 6 +++++-
 crates/ruma-serde-macros/src/lib.rs  | 1 +
 crates/ruma-serde/src/raw.rs         | 7 ++++++-
 4 files changed, 14 insertions(+), 2 deletions(-)

diff --git a/crates/ruma-client/src/lib.rs b/crates/ruma-client/src/lib.rs
index 4aefe50b..2357a553 100644
--- a/crates/ruma-client/src/lib.rs
+++ b/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;
diff --git a/crates/ruma-events-macros/src/lib.rs b/crates/ruma-events-macros/src/lib.rs
index 678c0656..fc4fdf51 100644
--- a/crates/ruma-events-macros/src/lib.rs
+++ b/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);
diff --git a/crates/ruma-serde-macros/src/lib.rs b/crates/ruma-serde-macros/src/lib.rs
index 92c9bd1c..207a76d4 100644
--- a/crates/ruma-serde-macros/src/lib.rs
+++ b/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;
 /// }
diff --git a/crates/ruma-serde/src/raw.rs b/crates/ruma-serde/src/raw.rs
index 04d7ac62..f21a2ecb 100644
--- a/crates/ruma-serde/src/raw.rs
+++ b/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)