-
Notifications
You must be signed in to change notification settings - Fork 2
Add attribute template #3
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from 2 commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,68 @@ | ||||||
| <?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 | ||||||
| { | ||||||
| /** | ||||||
| * 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 | ||||||
|
||||||
| * The name of this template | |
| * The name of this template. |
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| * The lucky numbers of this week | |
| * The lucky numbers of this week. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This (as well.as the first line of the class docblock) Is considered a Subject line. It should not contain punctuation.
It's not a sentence but a short summary like a ToC entry.
I like to think of it as a commit.message for the class/function/parameter. The first line in imperative mood extending the sentence "When this class/function/parameter is used it will..."
Applying the Beams-Rules will lead to clear and concise informations. I am willing to increase the 50 to 76 on the second rule, but that should be it.
If one can't summarize the class/function/parameter functionality in 76 characters, that usially is a hint that it does too much.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I have never heard of such a rule (and the $expense property has a period, so it's inconsistent right now either way). And IME, I disagree entirely. Very often there is context needed for a parameter that makes more sense on the parameter than in a description block. Most of my parameters have no description (because they're self-evident from the name and method), some have a short description, and some have lengthy descriptions for context. I don't see a reason to forbid the latter, for which complete sentences with proper punctuation is appropriate.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The summary of a docblock is described in the draft of psr-5. I updated that recently. In psr-5 we state that the dot at the end of the summary is optional, but recommended.
I think we didn't include anything about the description of a parameter. Although tags can have a longer description than just a short sentence, there is no definition on how such a description should be formatted.
I will put this on my list to address in psr-5.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I stumbled upon this similarity of a function/parameter/class description to a commit message just recently but it made perfect sense to me.
"when this parameter is used it will:" Merge two or more arrays1, Create an array by using one array for keys and another for its values2, Tokenize a string3
These are just some random examples from the PHP-Docs that seem to follow the same idea of an imperative sentence. BTW all of them without a dot at the end.
Yes! Admittedly in the parameter descriptions of all those examples that is no longer followed and none of the titles are in imperative mood any more.
Whether there is a dot at the end or not is not a hill I will die upon. But for me those sentences are the headline of the following more thorough description. The TOC entry. And in headlines we rarely find periods at the end of the sentence4.
On the other hand the Oracle Docs on how to write DocComments for the JavaDoc tool state that "The first sentence of each doc comment should be a summary sentence, containing a concise but complete description of the API item". They then highlight that it needs a dot at the end as that is a technical requirement for the tool. They do though not mention anything about Imperative mood or even a blank line between the summary/Headline and the remainder of the documentation text.
To me a clear structure like
# Summarize the class functionality
Describe the class functionality in more detail.
even in several paragraphs.
## Summarize the first method
Describe the first method in more detail.
### Summarize first parameter to method without details
### Summarize second parameter to method
Describe parameter in more detail.
...
makes the most sense.
But to make things short (after this lengthy excursion) - If that is covered in PER-5 we should just reference that.
I'll see how I can modify that...
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I meant "functions". People should des ribe what the functions do, not only the parameters.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
What functions? Do you mean methods should have docblocks? If so, say that directly.