Normally rustdoc generates the fn signature for you, and it does not show any macros or attributes applied to the function. Then it finds the #[doc] attributes attached to it from your comments and adds those. The #[embassy-executor::task] macro actually alters the function signature of an async function so that it can be spawned as a top level task, but then that is the only thing you can do with it. You can't use it as a normal async fn anymore.

I would like to get rustdoc to notate that this fn is special because it is marked as a top level task, and therefore, can not be called as an async fn as it looks like. I would like this to show prominently even on the higher navigation page listing functions so that the top level tasks immediately stand out from all other async functions. And it wold be nice to be able to have the #[task] macro be shown above the function signature when you click on the actual function, as a link and/or with a footnote warning that you can not use this as a normal async fn, but only pass it to spawn().

Is this possible?

2 posts - 2 participants

Read full topic