<html><head><meta http-equiv="Content-Type" content="text/html charset=us-ascii"></head><body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;" class=""><div class="">This is about documentation markup. Consider the following markup:</div><div class=""><br class=""></div><div class=""><font face="Menlo" class="">/// Converts integers to string.</font></div><div class=""><font face="Menlo" class="">func myFunction() {}</font></div><div class=""><br class=""></div><div class="">It renders like this: <a href="http://imgur.com/YHFu68b" class="">http://imgur.com/YHFu68b</a> </div><div class="">If you use a full sentence as the description, you end up instead with: <a href="http://imgur.com/Jzxe2RT" class="">http://imgur.com/Jzxe2RT</a></div><div class=""><br class=""></div><div class="">The latter over-emphasizes the function name. If you limit the description to a sentence fragment, the</div><div class="">declaration naturally continues to the description.</div><div class=""><br class=""></div><br class=""><div><blockquote type="cite" class=""><div class="">On Jan 29, 2016, at 9:27 AM, Patrick Gili <<a href="mailto:gili.patrick.r@gili-labs.com" class="">gili.patrick.r@gili-labs.com</a>> wrote:</div><br class="Apple-interchange-newline"><div class=""><meta http-equiv="Content-Type" content="text/html charset=us-ascii" class=""><div style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;" class="">Hi Erica,<div class=""><br class=""></div><div class="">This was in the documentation section, I didn't think this applied to the naming of functions/methods.</div><div class=""><br class=""></div><div class="">Cheers,</div><div class="">-Patrick</div><div class=""><br class=""><div class=""><blockquote type="cite" class=""><div class="">On Jan 29, 2016, at 11:11 AM, Erica Sadun <<a href="mailto:erica@ericasadun.com" class="">erica@ericasadun.com</a>> wrote:</div><br class="Apple-interchange-newline"><div class=""><meta http-equiv="Content-Type" content="text/html charset=us-ascii" class=""><div style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;" class=""><div class=""><blockquote type="cite" class=""><div class=""><div class="" style="font-family: Palatino-Roman; font-size: 14px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px;"><div class=""><div class="">Overall, I like the proposal. It provides sound guidance that can lead to consistent code in practice. However, there are some issues and concerns I have:</div><div class=""><br class=""></div><div class="">- Under "Fundamentals", there is a bullet called "Write a documentation comment...". Under this bullet, this is another bullet called "Use a single sentence fragment...". Why? I find sentence fragments often detract from clarity and concise nature, which can lead to confusion.</div></div></div></div></blockquote><div class=""><br class=""></div><div class="">This fragment is added to the name of the function so if you have a function named "myFunction", the descriptive fragment is "converts integers to strings." and the display is:</div><div class=""><br class=""></div><div class="">Description: myFunction converts integers to string.</div><br class=""></div><br class=""></div></div></blockquote></div><br class=""></div></div></div></blockquote></div><br class=""></body></html>