<html><head><meta http-equiv="Content-Type" content="text/html charset=utf-8"></head><body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;" class="">On Mar 28, 2016, at 10:05 PM, Erica Sadun <<a href="mailto:erica@ericasadun.com" class="">erica@ericasadun.com</a>> wrote:<br class=""><div><blockquote type="cite" 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 style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;" class=""><div class=""><br class=""></div><div class="">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.</div><div class=""><br class=""></div></div></div></blockquote></div><br class=""><div class="">The current markup includes: <font face="Menlo" class="">attention</font>, <font face="Menlo" class="">important</font>, <font face="Menlo" class="">note</font>, <font face="Menlo" class="">remark</font>, </div><div class="">and <font face="Menlo" class="">SeeAlso</font>, which could all theoretically convey this information. I don't</div><div class="">think <font face="Menlo" class="">RelatedTo</font> offers a distinct advantage over the existing <font face="Menlo" class="">SeeAlso</font> in </div><div class="">particular, as in most programming markup, <font face="Menlo" class="">SeeAlso</font> already provides </div><div class="">cross-references to related constructs, methods, files, and URLs.</div></div></blockquote><div><br class=""></div><div>I agree SeeAlso seems sufficient.</div><div><br class=""></div><blockquote type="cite" class=""><div style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;" class=""><div class="">I am moved particularly by the <font face="Menlo" class="">recommended</font>/<font face="Menlo" class="">recommendedOver</font> pair in</div><div class="">terms of pushing for a specific Swift keyword expansion. Let me go</div><div class="">for what I call the "<i class="">Hail Dave A</i>" defense on this one:</div><div class=""><br class=""></div><div class="">* Mutating and non-mutating pairs are specifically called out in the API naming guide. </div><div class="">* They reflect a specific Swift pattern that differentiates functional implementations </div><div class=""> from their related procedural cousins. </div><div class="">* Using mutation-specific keywords avoids ambiguity that might be introduced by </div><div class=""> "<font face="Menlo" class="">let self = nonMutatingCall</font>" patterns. These keywords support the developer in</div><div class=""> both directions.</div><div class="">* Using named keywords instantly identifies <i class="">why</i> the documentation is calling these items </div><div class=""> out and promoting their names, rather than promoting some general relationship. </div><div class="">* The keywords support the expert and guide the beginner, adding value in a way <font face="Menlo" class="">RelatedTo</font> cannot.</div><div class=""><br class=""></div><div class="">I believe localized vs non-localized string operations would be better covered</div><div class="">under the existing <font face="Menlo" class="">SeeAlso</font>. Localization is not a Swift-specific pattern the way mutable </div><div class="">pairing is. While common, there is no inherent language basis for relating these methods.</div></div></blockquote><br class=""></div><div>I’m not really seeing this, but in any case, I think you should start a new thread. This discussion is buried in an unrelated thread about set naming, so many possibly interested folks aren’t looking at it.</div><div><br class=""></div><div>-Chris</div><br class=""></body></html>