[swift-evolution] SetAlgebra naming update

[Erica Sadun]

> On Mar 28, 2016, at 10:25 PM, Chris Lattner <clattner at apple.com> wrote:
> 
> 
>> On Mar 28, 2016, at 5:34 PM, Erica Sadun via swift-evolution <swift-evolution at swift.org <mailto:swift-evolution at swift.org>> wrote:
>> 
>> That said, I'd really like to see a Swift Doc markup that allows you to mark
>> pairs of mutating/nonmutating functions, not from a compiler point of
>> view but in doc markup.
>> 
>> /// - nonmutatingVersion: 
>> /// - mutatingVersion:
>> 
>> What group handles expansion of the markup keywords and how can I file a
>> feature request asking for this to be added?
> 
> swift-evolution is the right place for this.  As I mentioned in a different thread, I think that having a more general “relatedto:” notion would be useful to have.  There are interesting relations between methods other than mutation.  One example is the localized vs non-localized versions of string operations, etc.
> 
> -Chris

The current markup includes: attention, important, note, remark, 
and SeeAlso, which could all theoretically convey this information.  I don't
think RelatedTo offers a distinct advantage over the existing SeeAlso in 
particular, as in most programming markup, SeeAlso already provides 
cross-references to related constructs, methods, files, and URLs.

I am moved particularly by the recommended/recommendedOver pair in
terms of pushing for a specific Swift keyword expansion.  Let me go
for what I call the "Hail Dave A" defense on this one:

* Mutating and non-mutating pairs are specifically called out in the API naming guide. 
* They reflect a specific Swift pattern that differentiates functional implementations 
  from their related procedural cousins.  
* Using mutation-specific keywords avoids ambiguity that might be introduced by 
  "let self = nonMutatingCall" patterns. These keywords support the developer in
   both directions.
* Using named keywords instantly identifies why the documentation is calling these items 
  out and promoting their names, rather than promoting some  general relationship. 
* The keywords support the expert and guide the beginner, adding value in a way RelatedTo cannot.

I believe localized vs non-localized string operations would be better covered
under the existing SeeAlso. Localization is not a Swift-specific pattern the way mutable 
pairing is. While common, there is no inherent language basis for relating these methods.

-- Erica

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