Merge #1093 #1127

1093: Add random example r=Dirbaio a=miathedev

Thanks Lulf for the help!

This should be added as example so other people can look it up easily.

With love,
Mia



1127: clean up doc comment generation r=Dirbaio a=Weshnaw

I noticed that when I created doc comments for my tasks that the doc comments got included on the inner function but not the outer functions, I personally prefer keeping the documentation as clean as possible so this PR aims to hide the inner function and then add doc comments to the outer function.

The actual changes include:
* adding #[doc(hidden)] onto the `task_inner` function
  * I flip flopped on this one because I could imagine someone may want this in their docs, but decided to include but I think arguments could be made either way
* copy the attributes from `task_inner` to `task_outer`
  * I don't work with proc_macros often so I am not entirely sure if the way I went about it is correct but it seems to work fine
    * specifically: using `parse_quote` to create the `task_outer` as a `ItemFn` then duplicating the attributes from `task_inner` to `task_outer`
  * I also am not sure if it's a good idea to duplicate all attributes over, but I honestly wasn't sure how to just get the just doc comment attributes

![OLD doc](https://user-images.githubusercontent.com/3748858/209456006-bfa6d40d-d3bf-4c1d-a2de-cf40828b58e5.png)
![NEW doc](https://user-images.githubusercontent.com/3748858/209456011-995363a3-f5b1-4ea3-9db9-1c566643efcb.png)


Co-authored-by: miathedev <mia@metzler.systems>
Co-authored-by: Brendon Fallquist <bfallquist@gmail.com>

embassy-macros/src/macros/task.rs

@@ -1,6 +1,7 @@
 use darling::FromMeta;
 use proc_macro2::TokenStream;
 use quote::{format_ident, quote};
+use syn::{parse_quote, ItemFn};
 
 use crate::util::ctxt::Ctxt;
 
@@ -57,13 +58,7 @@ pub fn run(args: syn::AttributeArgs, f: syn::ItemFn) -> Result<TokenStream, Toke
     task_inner.vis = syn::Visibility::Inherited;
     task_inner.sig.ident = task_inner_ident.clone();
 
-    let result = quote! {
-        // This is the user's task function, renamed.
-        // We put it outside the #task_ident fn below, because otherwise
-        // the items defined there (such as POOL) would be in scope
-        // in the user's code.
-        #task_inner
-
+    let mut task_outer: ItemFn = parse_quote! {
         #visibility fn #task_ident(#fargs) -> ::embassy_executor::SpawnToken<impl Sized> {
             type Fut = impl ::core::future::Future + 'static;
             static POOL: ::embassy_executor::raw::TaskPool<Fut, #pool_size> = ::embassy_executor::raw::TaskPool::new();
@@ -71,5 +66,18 @@ pub fn run(args: syn::AttributeArgs, f: syn::ItemFn) -> Result<TokenStream, Toke
         }
     };
 
+    task_outer.attrs.append(&mut task_inner.attrs.clone());
+
+    let result = quote! {
+        // This is the user's task function, renamed.
+        // We put it outside the #task_ident fn below, because otherwise
+        // the items defined there (such as POOL) would be in scope
+        // in the user's code.
+        #[doc(hidden)]
+        #task_inner
+
+        #task_outer
+    };
+
     Ok(result)
 }

examples/stm32wl/src/bin/random.rs

@@ -0,0 +1,33 @@
+#![no_std]
+#![no_main]
+#![feature(type_alias_impl_trait)]
+
+use defmt::*;
+use embassy_executor::Spawner;
+use embassy_stm32::pac;
+use embassy_stm32::rng::Rng;
+use {defmt_rtt as _, panic_probe as _};
+
+#[embassy_executor::main]
+async fn main(_spawner: Spawner) {
+    let mut config = embassy_stm32::Config::default();
+    config.rcc.mux = embassy_stm32::rcc::ClockSrc::HSE32;
+    config.rcc.enable_lsi = true; //Needed for RNG to work
+
+    let p = embassy_stm32::init(config);
+    unsafe {
+        pac::RCC.ccipr().modify(|w| {
+            w.set_rngsel(0b01);
+        });
+    }
+
+    info!("Hello World!");
+
+    let mut rng = Rng::new(p.RNG);
+
+    let mut buf = [0u8; 16];
+    unwrap!(rng.async_fill_bytes(&mut buf).await);
+    info!("random bytes: {:02x}", buf);
+
+    loop {}
+}