[swift-evolution] [swift-evolution-announce] [Review] SE-0023 API Design Guidelines

[Erica Sadun]

This is about documentation markup. Consider the following markup:

/// Converts integers to string.
func myFunction() {}

It renders like this: http://imgur.com/YHFu68b <http://imgur.com/YHFu68b> 
If you use a full sentence as the description, you end up instead with: http://imgur.com/Jzxe2RT <http://imgur.com/Jzxe2RT>

The latter over-emphasizes the function name. If you limit the description to a sentence fragment, the
declaration naturally continues to the description.


> On Jan 29, 2016, at 9:27 AM, Patrick Gili <gili.patrick.r at gili-labs.com> wrote:
> 
> Hi Erica,
> 
> This was in the documentation section, I didn't think this applied to the naming of functions/methods.
> 
> Cheers,
> -Patrick
> 
>> On Jan 29, 2016, at 11:11 AM, Erica Sadun <erica at ericasadun.com <mailto:erica at ericasadun.com>> wrote:
>> 
>>> 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:
>>> 
>>> - 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.
>> 
>> 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:
>> 
>> Description: myFunction converts integers to string.
>> 
>> 
> 

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20160129/c4099ed2/attachment.html>