From fcc04c8a6cd8792615ea7c4c9cbd77e5b0b2f352 Mon Sep 17 00:00:00 2001
From: Andreas Heigl <andreas@heigl.org>
Date: Tue, 30 Sep 2025 07:06:52 +0200
Subject: [PATCH 1/3] Add a template for a class-description

---
 Template.php | 46 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 46 insertions(+)
 create mode 100644 Template.php

diff --git a/Template.php b/Template.php
new file mode 100644
index 0000000..eee1adc
--- /dev/null
+++ b/Template.php
@@ -0,0 +1,46 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Fig\Attributes;
+
+/**
+ * One-Line summary of what the attribute does
+ *
+ * ## Target audience
+ *
+ * Implementors
+ * : Who should handle this attribute? Example: "static analysis tools"
+ * Users
+ * : Who adds this attribute to their code? Example: "packages that want to
+ *   safeguard their functions via static analysis
+ *
+ * Long explanation of what the attribute does and why it is relevant.
+ *
+ * Use citations[^citation] or [Links](https://example.com) in your text to make
+ * sure people understand the relevance and where you got your ideas from.
+ *
+ * If your Attribute has preconditions for usage you MUST use the keywords
+ * described in [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119).
+ * You SHOULD list them prominently.
+ *
+ * **Note:** DocBlock content MUST be Markdown formatted. Check out the
+ *   [Markdown-Guide](https://www.markdownguide.org/) for possible formatting
+ *
+ * Please also use code-snippets where appropriate
+ *
+ * ```php
+ *     <?php
+ *     echo 'Hello World';
+ * ```
+ *
+ * You MUST describe parameters to your Attribute extensively! You SHOULD use
+ * the well-known Annotations for that
+ *
+ * @param string $example_1 Does x and y
+ * @param boolean $example_2
+ *
+ * [^citation] https://en.wikipedia.org/wiki/Citation
+ */
+#[\Attribute(\Attribute::TARGET_CLASS)]
+final class Template {}

From c5d6e7864846accc68968739a1d943d21c0d68d5 Mon Sep 17 00:00:00 2001
From: Andreas Heigl <andreas@heigl.org>
Date: Tue, 30 Sep 2025 18:51:28 +0200
Subject: [PATCH 2/3] Improve the text according to reviews

This incorporates the suggestions from @crell and @jrfnl

Thanks for the input!

The main change is adding a function and moving the function-description
into the subsection
---
 Template.php | 44 +++++++++++++++++++++++++++++++++-----------
 1 file changed, 33 insertions(+), 11 deletions(-)

diff --git a/Template.php b/Template.php
index eee1adc..08aacd8 100644
--- a/Template.php
+++ b/Template.php
@@ -5,7 +5,7 @@
 namespace Fig\Attributes;
 
 /**
- * One-Line summary of what the attribute does
+ * One-Line summary of what the attribute does (PLAIN TEXT!)
  *
  * ## Target audience
  *
@@ -13,34 +13,56 @@
  * : Who should handle this attribute? Example: "static analysis tools"
  * Users
  * : Who adds this attribute to their code? Example: "packages that want to
- *   safeguard their functions via static analysis
+ *   safeguard their functions via static analysis"
+ *
+ * ## Purpose
  *
  * Long explanation of what the attribute does and why it is relevant.
  *
  * Use citations[^citation] or [Links](https://example.com) in your text to make
  * sure people understand the relevance and where you got your ideas from.
  *
+ * ## When should the attribute be applied ?
+ *
  * If your Attribute has preconditions for usage you MUST use the keywords
  * described in [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119).
  * You SHOULD list them prominently.
  *
  * **Note:** DocBlock content MUST be Markdown formatted. Check out the
  *   [Markdown-Guide](https://www.markdownguide.org/) for possible formatting
+ *   and keep in mind that the short description should not contain markdown.
+ *
+ * Keep your lines at a maximum of 80 Characters. It increases readability on
+ * smaller windows.
  *
  * Please also use code-snippets where appropriate
  *
  * ```php
- *     <?php
- *     echo 'Hello World';
+ * <?php
+ * echo 'Hello World';
  * ```
  *
- * You MUST describe parameters to your Attribute extensively! You SHOULD use
- * the well-known Annotations for that
- *
- * @param string $example_1 Does x and y
- * @param boolean $example_2
- *
  * [^citation] https://en.wikipedia.org/wiki/Citation
  */
 #[\Attribute(\Attribute::TARGET_CLASS)]
-final class Template {}
+class Template
+{
+    /**
+     * You MUST describe parameters to your Attribute extensively! You SHOULD use
+     * the well-known Annotations for that.
+     *
+     * Also, you SHOULD describe what the different functions do.
+     *
+     * @param string $name
+     *     The name of this template
+     * @param boolean $expose
+     *     Whether to expose this as an example or not.
+     * @param int[] $luckyNumbers
+     *     The lucky numbers of this week
+     */
+    public function __construct(
+        public readonly string $name,
+        public readonly bool $expose,
+        public readonly array $luckyNumbers
+    ) {}
+}

From b8e926c9ed4285eb9c93338fc82ee7802cbe2dba Mon Sep 17 00:00:00 2001
From: Andreas Heigl <andreas@heigl.org>
Date: Fri, 10 Oct 2025 07:27:45 +0200
Subject: [PATCH 3/3] Improve template-file

This movedthe template-file from a PHP-file to a markdown-file to not block the
`template` name for an attribute.

It also enhances the content slightly by referencing PSR-5, using dots at the
end of all the subject lines, changing "function" to "method" in one place and
extend the description of a parameter to show that multi-line is possible there
as well.
---
 .editorconfig               |  3 ++-
 Template.php => Template.md | 25 ++++++++++++++++---------
 2 files changed, 18 insertions(+), 10 deletions(-)
 rename Template.php => Template.md (75%)

diff --git a/.editorconfig b/.editorconfig
index cd8eb86..a8fbc70 100644
--- a/.editorconfig
+++ b/.editorconfig
@@ -10,6 +10,7 @@ indent_style = space
 end_of_line = lf
 insert_final_newline = true
 trim_trailing_whitespace = true
+max_line_length = 80
 
 [*.md]
-trim_trailing_whitespace = false
+trim_trailing_whitespace = true
diff --git a/Template.php b/Template.md
similarity index 75%
rename from Template.php
rename to Template.md
index 08aacd8..d7b4e77 100644
--- a/Template.php
+++ b/Template.md
@@ -1,3 +1,6 @@
+# A template for an attribute definition
+
+```php
 <?php
 
 declare(strict_types=1);
@@ -7,7 +10,7 @@
 /**
  * One-Line summary of what the attribute does (PLAIN TEXT!)
  *
- * ## Target audience
+ * ## Target audience.
  *
  * Implementors
  * : Who should handle this attribute? Example: "static analysis tools"
@@ -22,7 +25,7 @@
  * Use citations[^citation] or [Links](https://example.com) in your text to make
  * sure people understand the relevance and where you got your ideas from.
  *
- * ## When should the attribute be applied ?
+ * ## When should the attribute be applied?
  *
  * If your Attribute has preconditions for usage you MUST use the keywords
  * described in [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119).
@@ -48,17 +51,20 @@
 class Template
 {
     /**
-     * You MUST describe parameters to your Attribute extensively! You SHOULD use
-     * the well-known Annotations for that.
-     *
-     * Also, you SHOULD describe what the different functions do.
-     *
+     * Describe your methods extensively.
+     * 
+     * You also MUST describe parameters to your Attribute extensively! You 
+     * SHOULD use the DocBlock-format as described in PSR-5 for that.
+     * 
      * @param string $name
-     *     The name of this template
+     *     The name of this template.
+     * 
+     *     Parameter descriptions can span multiple lines. Make sure to
+     *     separate the subject from the text by a blank line.
      * @param boolean $expose
      *     Whether to expose this as an example or not.
      * @param int[] $luckyNumbers
-     *     The lucky numbers of this week
+     *     The lucky numbers of this week.
      */
     public function __construct(
         public readonly string $name,
@@ -66,3 +72,4 @@ public function __construct(
         public readonly array $luckyNumbers
     ) {}
 }
+```