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.
This commit is contained in:
Andreas Heigl
2025-10-10 07:27:45 +02:00
parent c5d6e78648
commit b8e926c9ed
2 changed files with 18 additions and 10 deletions

View File

@@ -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

View File

@@ -1,3 +1,6 @@
# A template for an attribute definition
```php
<?php
declare(strict_types=1);
@@ -7,7 +10,7 @@ namespace Fig\Attributes;
/**
* 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 @@ namespace Fig\Attributes;
* 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 @@ namespace Fig\Attributes;
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 @@ class Template
public readonly array $luckyNumbers
) {}
}
```