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 On Fri, 26 Oct 2018 at 16:56, Woody Gilk <[email protected]> wrote: > 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 <[email protected]> > 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 [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/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 [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/CAGOJM6Lqodnbz%2B8FoxDgku%2BN3g4CJwkoAgBChaiorLzLCdNdNw%40mail.gmail.com > <https://groups.google.com/d/msgid/php-fig/CAGOJM6Lqodnbz%2B8FoxDgku%2BN3g4CJwkoAgBChaiorLzLCdNdNw%40mail.gmail.com?utm_medium=email&utm_source=footer> > . > For more options, visit https://groups.google.com/d/optout. > -- Robbie Averill | Senior Developer 04 978 7330 http://silverstripe.com/ -- 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/CANv6TC3nhOgBVGFD8QpmZLmb8F89VXaR_1quoUV2i%2B1gcwpiOg%40mail.gmail.com. For more options, visit https://groups.google.com/d/optout.
