feat(xtask): Add check to ensure proc-macro generated user-space items are documented or hidden

[AnthonyGrondin]

Thank you for your contribution!

We appreciate the time and effort you've put into this pull request.
To help us review it efficiently, please ensure you've gone through the following checklist:

Submission Checklist 📝

• I have updated existing examples or added new ones (if applicable).
• I have used cargo xtask fmt-packages command to ensure that all changed code is formatted correctly.
• My changes were added to the CHANGELOG.md in the proper section.
• I have added necessary changes to user code to the latest Migration Guide.
• My changes are in accordance to the esp-rs developer guidelines

Extra:

• I have read the CONTRIBUTING.md guide and followed its instructions.

Pull Request Details 📖

Description

This is a naive attempt at checking rustdoc coverage on a proper binary, using all of the generated pro-macros to ensure that expanded code in the user's app is either documented or hidden.

Related: #1233

• Add a CI-facing xtask check that runs cargo rustdoc --document-private-items --show-coverage on examples/async/embassy_hello_world.
• Fail when private-item doc coverage is not 100.0%, catching undocumented macro-generated items in user-facing apps.
• Mark generated __main module in esp-hal-procmacros as #[doc(hidden)] and document example tasks to keep baseline coverage passing.

Testing

Tested locally by adding and removing #[doc(hidden)].
Will need a proper CI run to ensure it's fully working on all targets.

[Copilot]

Pull request overview

Adds a new xtask CI check to detect undocumented (or not-#[doc(hidden)]) proc-macro-generated items by running cargo rustdoc --document-private-items --show-coverage against a representative end-user binary example.

Changes:

• Run a new CI-facing xtask step that executes cargo rustdoc on examples/async/embassy_hello_world and enforces 100% private-item doc coverage.
• Update the embassy hello world async example to document an #[embassy_executor::task] function.
• Hide the proc-macro generated __main module in esp-hal-procmacros with #[doc(hidden)] to keep rustdoc coverage clean.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
xtask/src/main.rs	Adds the new “generated doc artifacts” rustdoc coverage check to CI checks.
examples/async/embassy_hello_world/src/main.rs	Documents a task function to satisfy private-item doc coverage.
esp-hal-procmacros/src/rtos_main.rs	Marks generated __main module as #[doc(hidden)] to avoid coverage failures from macro output.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

[bjoernQ]

the proc-macro changes look useful - not sure if just having unit tests for the macros wouldn't be enough

[bugadani]

Also please add a line about this to the developer guidelines, maybe copilot is smart enough to catch unwanted changes early.

[AnthonyGrondin]

the proc-macro changes look useful - not sure if just having unit tests for the macros wouldn't be enough

I'm not sure if this is easily feasible. Ultimately, it's what ends up in the final binary that matters. The current tests verify that the proc-macro matches a specific string, but documentation coverage is a bit more broad.

[AnthonyGrondin]

This makes me wonder if we should have a specifically tailored package to cover #[ram], #[handler], #[esp_rtos::main] all at once.

[bugadani]

I don't know... you're testing a set of macros, and nothing really guarantees that we won't add more, that won't be tested. At that point, doc coverage is essentially the same as the unit tests - we need to keep something in mind in order to test it, but the extra check just brings in extra complication and takes time to run.

Not to mention this uses 2 unstable features so it's pretty much guaranteed to break at some point for one reason or another.

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[AnthonyGrondin]

I don't know... you're testing a set of macros, and nothing really guarantees that we won't add more, that won't be tested. At that point, doc coverage is essentially the same as the unit tests - we need to keep something in mind in order to test it, but the extra check just brings in extra complication and takes time to run.

Not to mention this uses 2 unstable features so it's pretty much guaranteed to break at some point for one reason or another.

Yeah. This is quite an unstable situation, with no strong verification barriers. The current checked binary doesn't cover #[handler] but in my personal crate I saw it lacked documentation. If needed we can also introduce a binary in qa-test that spams all macros to cover all expansions.

The current architecture allows future extension like enforcing documentation coverage for all stabilized public items, if that's desired.

[github-actions]

New commits in main has made this PR unmergable. Please resolve the conflicts.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 5 comments.

[bugadani]

If you would please undo the CI and xtask changes, we could perhaps move forward here.

[AnthonyGrondin]

What do you mean? I thought we wanted this to run in nightly CI?

[bugadani]

Because the CI check needs to know about the potentially problematic macros, there's no point in running the CI check in the first place. The unit tests should be sufficient, I don't see the value in the complexity added to the xtask.

[AnthonyGrondin]

Got it! Fixed and rebased

[bugadani]

Thanks!

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.