Skip to content
Merged
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 68 additions & 0 deletions Template.php
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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* Also, you SHOULD describe what the different functions do.
* Also, you SHOULD describe what the different parameters do.

Copy link
Contributor Author

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.

Copy link
Contributor

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.

*
* @param string $name
* The name of this template
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* The name of this template
* 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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* The lucky numbers of this week
* The lucky numbers of this week.

Copy link
Contributor Author

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.

Copy link
Contributor

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.

Copy link
Member

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.

Copy link
Contributor Author

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

Footnotes

  1. https://www.php.net/manual/en/function.array-merge.php

  2. https://www.php.net/manual/en/function.array-combine.php

  3. https://www.php.net/manual/en/function.strtok.php

  4. https://cuttingedgepr.com/articles/does-a-headline-need-a-full-stop-or-period/

*/
public function __construct(
public readonly string $name,
public readonly bool $expose,
public readonly array $luckyNumbers
) {}
}
Loading