Merge pull request #476 from proptest-rs/attr-macro-doc

add doc comment to attr macro. Fixes #473

Author: rexmas

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