mirror of
https://github.com/php-fig/per-attributes.git
synced 2026-03-23 22:52:15 +01:00
b8e926c9ed
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.
2.2 KiB
2.2 KiB
A template for an attribute definition
<?php
declare(strict_types=1);
namespace Fig\Attributes;
/**
* One-Line summary of what the attribute does (PLAIN TEXT!)
*
* ## 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"
*
* ## 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';
* ```
*
* [^citation] https://en.wikipedia.org/wiki/Citation
*/
#[\Attribute(\Attribute::TARGET_CLASS)]
class Template
{
/**
* 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.
*
* 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.
*/
public function __construct(
public readonly string $name,
public readonly bool $expose,
public readonly array $luckyNumbers
) {}
}