[PSR-5] Summary

[Woody Gilk]

The PSR-5 recommendation for a summary doesn't make sense:

A Summary MUST end with either

• a full stop (.) followed by a line break
  
• or two sequential line breaks.

The following would be considered an invalid docblock under PSR-5...

/**
 * Opens a file if it is readable
 */
public function openReadable(string $file): File;
 
I think that the summary section should be modified to:

A Summary MUST end with two sequential line breaks, if the block contains any content other than the summary.

That seems most congruent with how people are using phpdoc, across all of the projects that I contribute to. Anyone else have thoughts on this?

--
Woody Gilk
https://shadowhand.me

[Joe T.]

Gets my vote. i always enforce a blank line between summary and any subsequent tags.

[Chuck Burgess]

Yes, I agree.  I believe this requirement in the original draft was in line with phpDocumentor's requirement that a Summary *and* Description should *both* be present in DocBlocks.  In that context, the requirement makes sense.

Since the spec is only delineating how the pieces in a DocBlock should be shaped, then your suggestion reads well.  I'll issue a PR on it, unless you want to, Woody.

CRB

[Woody Gilk]

I've made the PR: https://github.com/php-fig/fig-standards/pull/1106

Thanks!

--
Woody Gilk
https://shadowhand.me

--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.
To post to this group, send email to php...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/f60e8d3a-7385-4a5c-a9b2-6c1d5da6c732%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Miguel Rosales]

Changing the recommendation makes sense to me, but why would you want to remove all those full stops from the examples in the PR?? You can always say the full stop is optional, but the examples are better with them IMHO...

P.D. Personally I always use full stops myself, which makes even more sense if the summary is rather big and contains commas or even full stops inside...

[Woody Gilk]

>  if the summary is rather big and contains commas or even full stops inside

That violates the purpose of the summary. The summary is meant to be the "title" of a block, as per description:

> A Summary MUST contain an abstract of the "Structural Element" defining the purpose. It is RECOMMENDED for Summaries to span a single line or at most two, but not more than that.

It wouldn't make sense to write the chapter of a book as "The Boy Who Lived." instead of "The Boy Who Lived", right?

--
Woody Gilk
https://shadowhand.me

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/c107feea-0f98-49d9-bf86-ff87057660c1%40googlegroups.com.

[Larry Garfield]

On Friday, October 26, 2018 10:29:15 AM CDT Woody Gilk wrote:
> > if the summary is rather big and contains commas or even full stops
>
> inside
>
> That violates the purpose of the summary. The summary is meant to be the
>
> "title" of a block, as per description:
> > A Summary MUST contain an abstract of the "Structural Element" defining
>
> the purpose. It is RECOMMENDED for Summaries to span a single line or at
> most two, but not more than that.
>
> It wouldn't make sense to write the chapter of a book as "The Boy Who
> Lived." instead of "The Boy Who Lived", right?
> --
> Woody Gilk
> https://shadowhand.me

I am also in the always-period camp. Every docblock I've ever written has a
period on the summary, because that's how you end sentences.

I would also say they should be capped at one line, not just recommended to be
under 2 lines. If you need more than that, that's what the description is
for.

--Larry Garfield

[Woody Gilk]

Larry,

My survey was obviously not big enough. Having reviewed the existing phpdoc demos [1] and Symfony API documentation [2], removing the period would be a major BC break, as you stated on the PR.

I have updated the PR to require that a summary be separated by two line breaks instead.

Now... to go update a bunch of docblocks. ;)

[1]: http://demo.phpdoc.org/Responsive/classes/Cilex.Provider.JmsSerializerServiceProvider.html

[2]: https://api.symfony.com/4.1/Symfony/Component/DependencyInjection/Alias.html

--
Woody Gilk
https://shadowhand.me

--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+u...@googlegroups.com.
To post to this group, send email to php...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/11771111.PGZR9nQHo3%40vulcan.

[Robbie Averill]

Hi all,

While I rarely use full stops at the end of sentences in doc blocks myself, I acknowledge that I probably should. They are sentences rather than titles, so should probably have one.

I think though that enforcing them might be a little strict, perhaps suggesting it or mentioning that they are optional would be better.

Regards

Robbie

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/CAGOJM6Lqodnbz%2B8FoxDgku%2BN3g4CJwkoAgBChaiorLzLCdNdNw%40mail.gmail.com.

For more options, visit https://groups.google.com/d/optout.

--

Robbie Averill | Senior Developer

04 978 7330

http://silverstripe.com/

[Woody Gilk]

Optional can't be enforced with style checks. Hence, I would rather have a required specification.

--
Woody Gilk
https://shadowhand.me

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/CANv6TC3nhOgBVGFD8QpmZLmb8F89VXaR_1quoUV2i%2B1gcwpiOg%40mail.gmail.com.

[Chuck Burgess]

If enough people feel strongly about requiring the period, I won't stand in the way... but I think it's overkill for the spec.  I think just saying that "if any content (Description, tags) follows the Summary, there MUST be two CRLFs delineating the Summary from the rest" should be sufficient.  I don't think the spec insisting that the Summary be a proper sentence is necessary... it's good form, sure, but no static tools are going to tell me "Young man, this is Harvard University... we do not end our sentences with a preposition!!!".  I'd bet that 50% of the docblock Summaries in my experience are sentence fragments at best.  As such, I don't think the period on top of two CRLFs is necessary.  

Note that by not *demanding* a period, the spec is not saying "no periods allowed".  I think at least one response earlier seemed to imply that not having in the spec would somehow mean it would be prohibited instead.

CRB
about.me/ashnazg

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/CAGOJM6KVCrNmz-q3VJhgqy3gRwd0RL2%3D6KfmoSLkmA5b%3DchwZg%40mail.gmail.com.

[Miguel Rosales]

Just to make things clear, the "complaint" in my first comment wasn't about the fact that the spec should require full stops, but only about the fact that the PR supposedly created to correct the misleading 2-line-breaks-after-summary recommendation, was also deleting full stops from lots of summaries in the examples, when there was no need for that at all! 

If you ask me, I'd require full stops, but I do see how it may be overkill - what I do think is at least the examples should include them, as a suggestion for best practices, imho anyway.

[Ian Littman]

A full stop is consistent with other PSRs, as is two line breaks between summary and description. Particularly after PR 1107 is merged. I'm not commenting on whether the full stop should be required or optional, but requiring it to not exist would, as mentioned further up the thread, fly in the face of what's built out currently.

[Chuck Burgess]

Yes guys, I understand you both.  My comments are directed at the angle of discussion that the spec *should* **require** periods.  My argument is that they don't need to be explicitly required... but the spec doesn't care if they *are* used.  The spec should only care about the two CRLFs between Summary and anything after it, IMO.

I believe this is really the only open question right now... periods explicitly required to be in spec, or spec doesn't specify anything with regard to periods... all the examples can certainly include them.

CRB

[Woody Gilk]

I would be fine with eliminating the requirement for a full stop so long as the two line break requirement stays. The only problem I see with the full stop requirement is that prevents using other punctuation as a stop, unless said punctuation is declared in the grammar. That gets tricky with i18n, etc. Probably best to leave it out.

I will update the PR accordingly.

--
Woody Gilk
https://shadowhand.me

On Mon, Oct 29, 2018 at 3:10 PM Chuck Burgess <demon...@gmail.com> wrote:

Yes guys, I understand you both.  My comments are directed at the angle of discussion that the spec *should* **require** periods.  My argument is that they don't need to be explicitly required... but the spec doesn't care if they *are* used.  The spec should only care about the two CRLFs between Summary and anything after it, IMO.

I believe this is really the only open question right now... periods explicitly required to be in spec, or spec doesn't specify anything with regard to periods... all the examples can certainly include them.

CRB

On Monday, October 29, 2018 at 2:23:53 PM UTC-5, Ian Littman wrote:

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/8605136a-3af7-496d-9d7b-3f427c36e050%40googlegroups.com.

[Chuck Burgess]

Since this thread seems to have wrapped up, I've merged the PR.

CRB