From ebafcc67bc82c6b900fac9824952200c6491482a Mon Sep 17 00:00:00 2001
From: rexmas <rex@RexbookPro.local>
Date: Thu, 4 Jul 2024 10:03:55 -0700
Subject: [PATCH] add doc comment to attr macro. Fixes #473

---
 proptest-macro/src/lib.rs | 46 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 46 insertions(+)

diff --git a/proptest-macro/src/lib.rs b/proptest-macro/src/lib.rs
index ef0329a9..4b0367c3 100644
--- a/proptest-macro/src/lib.rs
+++ b/proptest-macro/src/lib.rs
@@ -2,6 +2,52 @@ use proc_macro::TokenStream;
 
 mod property_test;
 
+/// The `property_test` procedural macro simplifies the creation of property-based tests
+/// using the `proptest` crate. This macro provides a more concise syntax for writing tests
+/// that automatically generate test cases based on properties.
+///
+/// # Example
+///
+/// Using the `property_test` macro:
+///
+/// ```
+/// #[property_test]
+/// fn foo(x: i32) {
+///     assert_eq!(x, x);
+/// }
+/// ```
+///
+/// is roughly equivalent to:
+///
+/// ```
+/// proptest! {
+///     #[test]
+///     fn foo(x in any::<i32>()) {
+///         assert_eq!(x, x);
+///     }
+/// }
+/// ```
+///
+/// # Details
+///
+/// The `property_test` macro is used to define property-based tests, where the parameters
+/// of the test function are automatically generated by `proptest`. The macro takes care
+/// of setting up the test harness and generating input values, allowing the user to focus
+/// on writing the test logic.
+///
+/// # Attributes
+///
+/// The `property_test` macro can take an optional `config` attribute, which allows you to
+/// customize the configuration of the `proptest` runner.
+///
+/// E.g. running 100 cases:
+///
+/// ```rust
+/// #[property_test(config = "ProptestConfig { cases: 100, .. ProptestConfig::default() }")]
+/// fn foo(x: i32) {
+///     assert_eq!(x, x);
+/// }
+/// ```
 #[proc_macro_attribute]
 pub fn property_test(attr: TokenStream, item: TokenStream) -> TokenStream {
     property_test::property_test(attr.into(), item.into()).into()