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: > > 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. > > On Monday, October 29, 2018 at 2:12:38 PM UTC-5, Miguel Rosales wrote: >> >> 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. >> >> El lunes, 29 de octubre de 2018, 17:45:36 (UTC), Chuck Burgess escribió: >>> >>> 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 <http://about.me/ashnazg>* >>> >>> >>> On Sat, Oct 27, 2018 at 2:15 PM Woody Gilk <[email protected]> wrote: >>> >>>> Optional can't be enforced with style checks. Hence, I would rather >>>> have a required specification. >>>> -- >>>> Woody Gilk >>>> https://shadowhand.me >>>> >>>> >>>> On Sat, Oct 27, 2018 at 12:28 PM Robbie Averill < >>>> [email protected]> wrote: >>>> >>>>> 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 >>>>> >>>>> <https://groups.google.com/d/msgid/php-fig/CANv6TC3nhOgBVGFD8QpmZLmb8F89VXaR_1quoUV2i%2B1gcwpiOg%40mail.gmail.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/CAGOJM6KVCrNmz-q3VJhgqy3gRwd0RL2%3D6KfmoSLkmA5b%3DchwZg%40mail.gmail.com >>>> >>>> <https://groups.google.com/d/msgid/php-fig/CAGOJM6KVCrNmz-q3VJhgqy3gRwd0RL2%3D6KfmoSLkmA5b%3DchwZg%40mail.gmail.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/0a29835d-547a-49fb-9e21-6281fa30295e%40googlegroups.com. For more options, visit https://groups.google.com/d/optout.
