rustdoc cleanup: use rustdoc attribute

[phip1611]

• Cleanup of rustdoc.
• Use rustdoc attribute instead of a program argument.
• Fixed a rustdoc bug.

The disadvantage is now that people can't run cargo doc as this fails now. They must use cargo xtask doc or cargo doc --features alloc,exts,logger.

PS: We are right now in a time where there are changes regarding the "missing_doc_code_examples" lint inside latest upstream/nightly Rust. 14 days ago, this tracking issue was created. Relevant for us is that #![allow(missing_doc_code_examples)] is deprecated but #![allow(rustdoc::missing_doc_code_examples)] requires #![feature(rustdoc_missing_doc_code_examples)].

Checklist

• Sensible git history (for example, squash "typo" or "fix" commits): See the
  Rewriting History guide for
  help.
• Update the changelog (if necessary)

[phip1611]

oh no, this breaks our nightly MSRV

https://github.com/rust-osdev/uefi-rs/actions/runs/3126569058/jobs/5072215764

How do we want to cope with that? Bumping our MSRV? @nicholasbishop

I added a commit that bumps the MSRV.. if we go this way, we can also use un-revert #506

[nicholasbishop]

Thinking through some tradeoffs and possibilities for nightly MSRV:

1. I think for nice-to-have changes that require a nightly MSRV bump, we could just pick some kinda arbitrary not-too-short, not-too-long timeframe to decide when a bump is allowed. I would propose maybe three months, so that would currently allow bumping to nightly-2022-06-27.
2. But sometimes, upstream changes will force us to pick a newer version. For example, Namespace the asm! macro rust-lang/rust#84019 forced some code changes in uefi-rs. When something like that occurs we would immediately bump up the nightly MSRV and then any nice-to-have changes that were blocked could immediately go in.
3. Alternatively, we could add some cfg code to try and support both new and slightly older nightly compilers. That could be done by adding some temporary features at the Cargo level (like bytemuck does for example), or by enabling some other unstable features like cfg_version or cfg_accessible. Obviously that path can get a bit more complicated than just bumping the nightly MSRV :)

Thoughts on those alternatives?

[phip1611]

Okay, I see. Intuitively, I'm against additional complexity with cfg-magic.

When something like that occurs we would immediately bump up the nightly MSRV and then any nice-to-have changes that were blocked could immediately go in.

Fully agree. For "unimportant MSRV bumps", I think, having accepted PRs on hold, maybe with a special tag, is a good idea.

I would propose maybe three months, so that would currently allow bumping to nightly-2022-06-27.

Three months sound good.

What's a good label name? @nicholasbishop

• accepted-on-hold
• msrv-bump-on-hold
• ???

[nicholasbishop]

Oops, missed that question before. I added a needs-msrv-bump label for this PR and another new PR.

[phip1611]

I'm closing this as it seems that rust-lang/rust#101730 will take a few months until something will land in the latest nightly. Also, there is no big benefit here. Hence, we shold close this PR for now.