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 On Fri, Oct 26, 2018 at 10:43 AM Larry Garfield <la...@garfieldtech.com> wrote: > 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 > > -- > 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+unsubscr...@googlegroups.com. > To post to this group, send email to php-fig@googlegroups.com. > To view this discussion on the web visit > https://groups.google.com/d/msgid/php-fig/11771111.PGZR9nQHo3%40vulcan. > 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 php-fig+unsubscr...@googlegroups.com. To post to this group, send email to php-fig@googlegroups.com. 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.
