> 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 On Fri, Oct 26, 2018 at 10:18 AM Miguel Rosales <[email protected]> wrote: > 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... > > El viernes, 26 de octubre de 2018, 15:48:10 (UTC+1), Woody Gilk escribió: >> >> I've made the PR: https://github.com/php-fig/fig-standards/pull/1106 >> >> Thanks! >> -- >> Woody Gilk >> https://shadowhand.me >> >> >> On Fri, Oct 26, 2018 at 8:19 AM Chuck Burgess <[email protected]> wrote: >> >>> 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 >>> >>> On Thursday, October 25, 2018 at 1:54:51 PM UTC-5, Woody Gilk wrote: >>>> >>>> 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 >>>> >>> -- >>> 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 [email protected]. >>> To post to this group, send email to [email protected]. >>> To view this discussion on the web visit >>> https://groups.google.com/d/msgid/php-fig/f60e8d3a-7385-4a5c-a9b2-6c1d5da6c732%40googlegroups.com >>> <https://groups.google.com/d/msgid/php-fig/f60e8d3a-7385-4a5c-a9b2-6c1d5da6c732%40googlegroups.com?utm_medium=email&utm_source=footer> >>> . >>> For more options, visit https://groups.google.com/d/optout. >>> >> -- > 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 [email protected]. > To post to this group, send email to [email protected]. > To view this discussion on the web visit > https://groups.google.com/d/msgid/php-fig/c107feea-0f98-49d9-bf86-ff87057660c1%40googlegroups.com > <https://groups.google.com/d/msgid/php-fig/c107feea-0f98-49d9-bf86-ff87057660c1%40googlegroups.com?utm_medium=email&utm_source=footer> > . > For more options, visit https://groups.google.com/d/optout. > -- 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 [email protected]. To post to this group, send email to [email protected]. To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/CAGOJM6Lz6qNLG%2BGDRLa_Nxfs-_x3osvsj0gfr_5%2BRAGFN2Qo5A%40mail.gmail.com. For more options, visit https://groups.google.com/d/optout.
