Generated documentation should include feature-gated APIs

[bugadani]

the S3 docs for example don't indicate that there is a #[main] macro (or a whole embassy support module) provided by the crate.

[jessebraham]

Probably not going to do this for the upcoming releases (hopefully coming this week), but will get it done for the next round. Would like to see #976 either merged or closed before I do any work here, as that will change things a fair bit.

[jessebraham]

At least the main macro has been moved to esp-hal-embassy now, and we do enable the ci feature when building documentation for esp-hal, so I believe this issue can be closed. If there are any APIs which are still not present in the documentation please feel free to re-open this issue, or to open a new one.

[bjoernQ]

I agree this is done.

I wonder if we should have #![feature(doc_auto_cfg)] - the downside is that we have a lot of cfgs for chip-specific things so we end up with something like this, then:

I guess this might be more confusing to users than it helps

Ah ok ... found something.

We could have #![feature(doc_cfg)] and for the feature-gated items we could do something like this:

#[doc(cfg(feature = "async"))]
#[cfg(feature = "async")]
pub mod asynch {
...
}

But certainly, another issue - do we have such an issue (can't find it) or should I create a new one. Probably we should also say something about that in the HAL-developer docs

[jessebraham]

We could have #![feature(doc_cfg)] and for the feature-gated items we could do something like this:

#[doc(cfg(feature = "async"))]
#[cfg(feature = "async")]
pub mod asynch {
...
}

But certainly, another issue - do we have such an issue (can't find it) or should I create a new one. Probably we should also say something about that in the HAL-developer docs

There's already a task in the documentation improvements issue for this, it just never got its own issue opened.