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().
You can write a /// documentation or #[doc = "..."] with whatever notice you want, including styling. If it is in the first paragraph, then it will show on the module page too.
Oh, right... it's not the first #[doc] that make the subject line, it's everything up to the first empty #[doc]. I think I tried having the macro add a #[doc] first, but then it got kind of munged into the existing doc subject line, and I didn't like that, so I moved it to the end. Maybe that's exactly what I should have done... have the macro add a #[doc] at the start to prefix the first paragraph with something like Task: so it sticks out on the module page, and maybe make it also a footnote so the longer explanation shows up further down when you actually read about the function?
Maybe it would also be nice to be able to organize the structure of the docs so that all of the top level tasks ( or threads in a non async threaded program ) are grouped together. But I guess that's not something you can really do with #[doc] alone, so maybe just have to to do it with modules? Like have a threads or tasks mod in main to hold the master top level threads/tasks, even if it is only to keep them organized in the documentation and they really just call straight into other functions in other modules for the actual implementation?
Right, modules are currently the only way to organize items. I do think there might be interest in a feature to replace rustdoc’s grouping of items in a module by kind with explicitly declared grouping, but such a feature doesn’t exist today.