doc: add README to embassy-macro

Documents the main and task macros.

embassy-macros/src/lib.rs

@@ -1,3 +1,4 @@
+#![doc = include_str!("../README.md")]
 extern crate proc_macro;
 
 use proc_macro::TokenStream;
@@ -6,6 +7,36 @@ mod macros;
 mod util;
 use macros::*;
 
+/// Declares an async task that can be run by `embassy-executor`. The optional `pool_size` parameter can be used to specify how
+/// many concurrent tasks can be spawned (default is 1) for the function.
+///
+///
+/// The following restrictions apply:
+///
+/// * The function must be declared `async`.
+/// * The function must not use generics.
+/// * The optional `pool_size` attribute must be 1 or greater.
+///
+///
+/// ## Examples
+///
+/// Declaring a task taking no arguments:
+///
+/// ``` rust
+/// #[embassy_executor::task]
+/// async fn mytask() {
+///     // Function body
+/// }
+/// ```
+///
+/// Declaring a task with a given pool size:
+///
+/// ``` rust
+/// #[embassy_executor::task(pool_size = 4)]
+/// async fn mytask() {
+///     // Function body
+/// }
+/// ```
 #[proc_macro_attribute]
 pub fn task(args: TokenStream, item: TokenStream) -> TokenStream {
     let args = syn::parse_macro_input!(args as syn::AttributeArgs);
@@ -14,6 +45,24 @@ pub fn task(args: TokenStream, item: TokenStream) -> TokenStream {
     task::run(args, f).unwrap_or_else(|x| x).into()
 }
 
+/// Creates a new `executor` instance and declares an application entry point spawning the corresponding function body as an async task.
+///
+/// The following restrictions apply:
+///
+/// * The function must accept exactly 1 parameter, an `embassy_executor::Spawner` handle that it can use to spawn additional tasks.
+/// * The function must be declared `async`.
+/// * The function must not use generics.
+/// * Only a single `main` task may be declared.
+///
+/// ## Examples
+/// Spawning a task:
+///
+/// ``` rust
+/// #[embassy_executor::main]
+/// async fn main(_s: embassy_executor::Spawner) {
+///     // Function body
+/// }
+/// ```
 #[proc_macro_attribute]
 pub fn main(args: TokenStream, item: TokenStream) -> TokenStream {
     let args = syn::parse_macro_input!(args as syn::AttributeArgs);