From f102b4b007b373cda647d0a3c2992ed82181205d Mon Sep 17 00:00:00 2001
From: Timo <dev@2515.ch>
Date: Tue, 3 Dec 2024 12:09:33 +0100
Subject: [PATCH] Improve generated doc

---
 Cargo.toml        |  3 +++
 README.md         |  9 ++++++---
 macros/src/lib.rs | 12 +++++++++---
 src/lib.rs        |  1 +
 4 files changed, 19 insertions(+), 6 deletions(-)

diff --git a/Cargo.toml b/Cargo.toml
index d2bbbd2..8c25e32 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -8,6 +8,9 @@ keywords = ["embedded", "test", "testing", "test-runner", "test-framework"]
 description = "A test harness and runner for embedded devices"
 categories = ["embedded", "no-std", "development-tools::testing"]
 
+[package.metadata.docs.rs]
+default-target = "riscv32imac-unknown-none-elf"
+
 [dependencies]
 semihosting = { version = "0.1.7", features = ["args"] }
 embedded-test-macros = { version = "0.6.0", path = "./macros" }
diff --git a/README.md b/README.md
index 2bff2cd..7e3b19d 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,7 @@
 # Embedded Test
 
 [![Crates.io](https://img.shields.io/crates/v/embedded-test?labelColor=1C2C2E&color=C96329&logo=Rust&style=flat-square)](https://crates.io/crates/embedded-test)
+[![Documentation](https://docs.rs/embedded-test/badge.svg)](https://docs.rs/embedded-test)
 ![Crates.io](https://img.shields.io/crates/l/embedded-test?labelColor=1C2C2E&style=flat-square)
 
 The embedded-test library provides a test harness for embedded systems (riscv, arm and xtensa).
@@ -38,7 +39,6 @@ Add the following to your `Cargo.toml`:
 [dev-dependencies]
 embedded-test = { version = "0.6.0" }
 
-
 [[test]]
 name = "example_test"
 harness = false
@@ -148,12 +148,15 @@ mod tests {
 | `external-executor`  | No       | Allows you to bring your own embassy executor which you need to pass to the `#[tests]` macro (e.g. `#[embedded_test::tests(executor = esp_hal::embassy::executor::thread::Executor::new())]`) |
 | `xtensa-semihosting` | No       | Enables semihosting for xtensa targets.                                                                                                                                                       |
 
+Please also note the doc for
+the [Attribute Macro embedded_test::tests](https://docs.rs/embedded-test/latest/embedded-test/attr.tests.html).
+
 ## License
 
 Licensed under either of:
 
-- Apache License, Version 2.0 (http://www.apache.org/licenses/LICENSE-2.0)
-- MIT license (http://opensource.org/licenses/MIT)
+- [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0)
+- [MIT license](http://opensource.org/licenses/MIT)
 
 at your option.
 
diff --git a/macros/src/lib.rs b/macros/src/lib.rs
index 2e3219c..4958a15 100644
--- a/macros/src/lib.rs
+++ b/macros/src/lib.rs
@@ -8,6 +8,11 @@ use syn::{parse, spanned::Spanned, Attribute, Item, ItemFn, ItemMod, ReturnType,
 
 /// Attribute to be placed on the test suite's module.
 ///
+/// ## Arguments
+/// - `default-timeout`: The default timeout in seconds for all tests in the suite. This can be overridden on a per-test basis. If not specified here or on a per-test basis, the default timeout is 60 seconds.
+/// - `executor`: The custom executor to use for running async tests. This is only required if the features `embassy` and `external-executor` are enabled.
+/// - `setup`: A function that will be called before running the tests. This can be used to setup logging or other global state.
+///
 /// ## Examples
 ///
 /// Define a test suite with a single test:
@@ -27,10 +32,10 @@ use syn::{parse, spanned::Spanned, Attribute, Item, ItemFn, ItemMod, ReturnType,
 /// }
 /// ```
 ///
-/// Define a test suite with a default timeout, and per-test timeouts:
+/// Define a test suite and customize everything:
 ///
 /// ```rust,no_run
-/// #[embedded_test::tests(default_timeout = 10)]
+/// #[embedded_test::tests(default_timeout = 10, executor = embassy::executor::Executor::new(), setup = rtt_target::rtt_init_log!())]
 /// mod tests {
 ///     #[init]
 ///     fn init() {
@@ -39,7 +44,8 @@ use syn::{parse, spanned::Spanned, Attribute, Item, ItemFn, ItemMod, ReturnType,
 ///
 ///     #[test]
 ///     fn test() {
-///        // Test the hardware
+///         log::info("Start....")
+///         // Test the hardware
 ///     }
 ///
 ///     #[test]
diff --git a/src/lib.rs b/src/lib.rs
index 599e235..1dd8ba2 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,6 +1,7 @@
 // Copied from https://github.com/knurling-rs/defmt/blob/main/firmware/defmt-test/src/lib.rs
 
 #![no_std]
+#![cfg_attr(not(doctest), doc = include_str!("../README.md"))]
 
 mod fmt;