<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=""><br class=""><div><blockquote type="cite" class=""><div class="">On Mar 28, 2016, at 10:25 PM, Chris Lattner <<a href="mailto:clattner@apple.com" class="">clattner@apple.com</a>> wrote:</div><br class="Apple-interchange-newline"><div class=""><meta http-equiv="Content-Type" content="text/html charset=utf-8" class=""><div style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;" class=""><br class=""><div class=""><blockquote type="cite" class=""><div class="">On Mar 28, 2016, at 5:34 PM, Erica Sadun via swift-evolution <<a href="mailto:swift-evolution@swift.org" class="">swift-evolution@swift.org</a>> wrote:</div><br class="Apple-interchange-newline"><div class=""><div class="" style="font-family: Helvetica; font-size: 12px; font-style: normal; font-variant-caps: 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;">That said, I'd really like to see a Swift Doc markup that allows you to mark</div><div class="" style="font-family: Helvetica; font-size: 12px; font-style: normal; font-variant-caps: 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;">pairs of mutating/nonmutating functions, not from a compiler point of</div><div class="" style="font-family: Helvetica; font-size: 12px; font-style: normal; font-variant-caps: 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;">view but in doc markup.</div><div class="" style="font-family: Helvetica; font-size: 12px; font-style: normal; font-variant-caps: 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;"><br class=""></div><div class="" style="font-family: Helvetica; font-size: 12px; font-style: normal; font-variant-caps: 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;"><font face="Menlo" class="">/// - nonmutatingVersion: </font></div><div class="" style="font-family: Helvetica; font-size: 12px; font-style: normal; font-variant-caps: 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;"><font face="Menlo" class="">/// - mutatingVersion:</font></div><div class="" style="font-family: Helvetica; font-size: 12px; font-style: normal; font-variant-caps: 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;"><br class=""></div><div class="" style="font-family: Helvetica; font-size: 12px; font-style: normal; font-variant-caps: 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;">What group handles expansion of the markup keywords and how can I file a</div><div class="" style="font-family: Helvetica; font-size: 12px; font-style: normal; font-variant-caps: 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;">feature request asking for this to be added?</div></div></blockquote><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 class="">-Chris</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 class=""><br class=""></div><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 class=""><br class=""></div><div class="">-- Erica</div><div class=""><br class=""></div></body></html>