Avoid doctest errors

[kornelski]

It seems like proc macros don't work in doctests:

test src/lib.rs -  (line 167) ... FAILED
test src/lib.rs -  (line 154) ... FAILED
test src/lib.rs -  (line 141) ... FAILED

error[E0433]: failed to resolve: could not find main in async_std

--> src/lib.rs:146:14
  |
8 | #[async_std::main]
  |              ^^^^ could not find `main` in `async_std`

The problem is visible when running cargo test --all. Tested on Rust 1.40 and 1.42 nightly.

[yoshuawuyts]

@kornelski in order to run the tests a few features need to be enabled:

$ cargo test --all --features 'attributes,unstable'

This is the way it's setup in our CI as well. Though as evidenced by this PR it's not discoverable, and we should at the very least document this in the README. I wish we could add this to profiles somehow, but I don't believe we can.

[profiles.test]
features = [ "attributes", "unstable" ]

[kornelski]

That's unexpected indeed.

Doctests are an odd case, but for tests in general I expect them to be gated by the same flags as the features implementations are, so that cargo test only tests enabled features.

Maybe these doctests could be made conditional? This seems to be a supported syntax:

#[cfg_attr(feature = "attributes", doc = "#[async_std::main]")]

[kornelski]

cfg_attr actually works!

[yoshuawuyts]

Didn't know this was possible -- but this seems reasonable; thanks heaps!

[yoshuawuyts]

Ah, it seems we're missing a cargo fmt pass. CI is failing. Would you mind updating?

[kornelski]

Sorry, no.

rustfmt doesn't understand this syntax and breaks Markdown in the comments.

I'm incredibly disappointed that rustfmt missed the point of gofmt. It unconditionally overrides all human decisions, which makes it a dumb and destructive tool, unlike gofmt which more or less only cleans up known-bad formatting. Because of that I think unconditionally using rustfmt is a bad idea, and I'm not going to use rustfmt.

[k-nasa]

Thank you for a great hack!

Isn't this cause here?

async-std/rustfmt.toml

Line 2 in 0eb5ca1

format_code_in_doc_comments = true

I agree to remove rustfmt from CI if it gets in the way, but I think it would be better to remove the format_code_in_doc_comments option and keep using it.

What do you think ❓

[taiki-e]

Yeah, rustfmt error is bug/limitation of unstable format_code_in_doc_comments option.

Removing usage of format_code_in_doc_comments option should be the simplest fix, if we keep using rustfmt.
And I prefer to remove usage of this option for now because of the following reasons:

• this option is unstable
• (AFAIK) many docs with examples of this crate are in macros and rustfmt doesn't format code in macros, so are the benefits of using this option in this crate should not be very big.

---

fwiw: to keep using format_code_in_doc_comments, use cfg on hidden function instead of using #[doc] attribute, like:

/// ```
/// # #[cfg(feature = "attributes")]
/// # fn dox() {
/// examples...
/// # }
/// ```

[k-nasa]

ping @kornelski

[kornelski]

Sorry, I don't like enforced rustfmt checks, and I'm not going to satify rustfmt's arbitrary requirements.