docs: adr-004-metadata-prefix

Author: Chemaclass

adrs/adr-004-metadata-prefix.md

@@ -0,0 +1,37 @@
+# Title: Prefix metadata comments with @
+
+* Status: accepted
+* Authors: @Chemaclass
+* Date: 2025-05-29
+
+
+## Context and Problem Statement
+
+Data providers are defined via a special comment `# data_provider`. We want to
+clearly differentiate these meta comments from ordinary comments.
+
+## Considered Options
+
+* Keep using `# data_provider` as is.
+* Introduce an `@` prefix for special comments while supporting the old syntax.
+
+## Decision Outcome
+
+We decided to prefix the metadata provider directives with `@`,
+eg: using `# @data_provider provider_name`.
+
+> The previous form without the prefix is still supported for backward compatibility but is now deprecated.
+
+### Positive Consequences
+
+* Highlights special bashunit directives clearly.
+* Allows future directives to consistently use the `@` prefix.
+
+### Negative Consequences
+
+* Projects must eventually update old comments to the new syntax.
+
+## Technical Details
+
+`helper::get_provider_data` now matches both `# @data_provider` and the old
+`# data_provider` when locating provider functions.

docs/blog/2024-09-01-release-0-15.md

@@ -51,7 +51,7 @@ BASHUNIT_REPORT_HTML=
 
 ::: code-group
 ```bash [example_test.sh]
-# data_provider provider_directories
+# @data_provider provider_directories
 function test_directory_exists() {
   local outro=$1
   local directory=$2

docs/data-providers.md

@@ -13,9 +13,12 @@ Each run is treated as a separate test, so it can pass or fail independently. Pl
 
 A data provider function is specified as follows:
 
+> **Note**: The previous `# data_provider` syntax is still supported but
+> deprecated. Prefer using the `@` prefix going forward.
+
 ::: code-group
 ```bash [Example]
-# data_provider provider_function_name
+# @data_provider provider_function_name
 function test_my_test_case() {
   ...
 }
@@ -32,7 +35,7 @@ argument position.
 
 ::: code-group
 ```bash [example_test.sh]
-# data_provider fizz_numbers
+# @data_provider fizz_numbers
 function test_returns_fizz_when_multiple_of_::1::_like_::2::_given() {
   # ...
 }
@@ -53,7 +56,7 @@ Running example_test.sh
 
 ::: code-group
 ```bash [example_test.sh]
-# data_provider provider_directories
+# @data_provider provider_directories
 function test_directories_exists() {
   local dir1=$1
   local dir2=$2
@@ -78,7 +81,7 @@ Running example_test.sh
 
 ::: code-group
 ```bash [example_test.sh]
-# data_provider provider_directories
+# @data_provider provider_directories
 function test_directory_exists() {
   local directory=$1
 
@@ -103,7 +106,7 @@ Running example_test.sh
 
 ::: code-group
 ```bash [example_test.sh]
-# data_provider provider_directories
+# @data_provider provider_directories
 function test_directory_exists() {
   local outro=$1
   local directory=$2