Add reasons for each doctest ignore #569
Conversation
ShadowJonathan
changed the title
crates/ruma-events-macros/src/lib.rs
Outdated
| //// TODO: Change above (`<EventKind as Parse>::parse`) to [] after fully qualified syntax is supported: | ||
| //// https://github.com/rust-lang/rust/issues/74563 |
There was a problem hiding this comment.
Why does this commend start with four /es?
There was a problem hiding this comment.
To leave it out of the actual doc, its more a comment on the documentation itself.
https://doc.rust-lang.org/stable/reference/comments.html#doc-comments
// - Only a comment
/// - Outer line doc (exactly 3 slashes)
//// - Only a comment
There was a problem hiding this comment.
I understand that that makes it not a doc comment but I've never seen four slashes as "comment on docs" before.
There was a problem hiding this comment.
Utilizing three, imo, felt more like a "lowering" from the doc, making four then is more like "above" the doc.
| @@ -27,6 +27,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) | |||
There was a problem hiding this comment.
I don't really understand this TODO comment.. This ignore is probably fine.
There was a problem hiding this comment.
I'm providing reasons as to why each doctest is ignored, it's arguably bad to leave it ignored as-is, but at least i'm providing reasons as to why its ignored, so someone in the future can pick up on it.
There was a problem hiding this comment.
I get that, but I don't really understand how "more extensively" documenting something here would resolve the ignore.
There was a problem hiding this comment.
There's some blurbs of doctest underneath this comment, I know that writing a more "complete" doctest will resolve the run and compilation errors, but at the moment i dont know how to do it, ergo "more extensively documented"
Fixes #541.
This adds the actual reason why some tests cannot be
no_run, and one actual TODO label forruma-events-macros.