Merge pull request #1066 from embassy-rs/embassy-macros-doc

doc: add README to embassy-macro

embassy-macros/README.md

@@ -0,0 +1,21 @@
+# embassy-macros
+
+An [Embassy](https://embassy.dev) project.
+
+Macros for creating the main entry point and tasks that can be spawned by `embassy-executor`. 
+
+NOTE: The macros are re-exported by the `embassy-executor` crate which should be used instead of adding a direct dependency on the `embassy-macros` crate.
+
+## Minimum supported Rust version (MSRV)
+
+The `task` and `main` macros require the type alias impl trait (TAIT) nightly feature in order to compile.
+
+## License
+
+This work is licensed under either of
+
+- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or
+  <http://www.apache.org/licenses/LICENSE-2.0>)
+- MIT license ([LICENSE-MIT](LICENSE-MIT) or <http://opensource.org/licenses/MIT>)
+
+at your option.

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);