<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 &lt;<a href="mailto:clattner@apple.com" class="">clattner@apple.com</a>&gt; 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 &lt;<a href="mailto:swift-evolution@swift.org" class="">swift-evolution@swift.org</a>&gt; 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:&nbsp;</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. &nbsp;As I mentioned in a different thread, I think that having a more general “relatedto:” notion would be useful to have. &nbsp;There are interesting relations between methods other than mutation. &nbsp;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>,&nbsp;</div><div class="">and <font face="Menlo" class="">SeeAlso</font>, which could all theoretically convey this information. &nbsp;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&nbsp;</div><div class="">particular, as in most programming markup, <font face="Menlo" class="">SeeAlso</font>&nbsp;already provides&nbsp;</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. &nbsp;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.&nbsp;</div><div class="">* They reflect a specific Swift pattern that differentiates functional implementations&nbsp;</div><div class="">&nbsp; from their related procedural cousins. &nbsp;</div><div class="">* Using mutation-specific keywords avoids ambiguity that might be introduced by&nbsp;</div><div class="">&nbsp; "<font face="Menlo" class="">let self = nonMutatingCall</font>" patterns. These keywords support the developer in</div><div class="">&nbsp; &nbsp;both directions.</div><div class="">* Using named keywords instantly identifies <i class="">why</i>&nbsp;the documentation is calling these items&nbsp;</div><div class="">&nbsp; out and promoting their names, rather than promoting some &nbsp;general relationship.&nbsp;</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>.&nbsp;Localization is not a Swift-specific pattern the way mutable&nbsp;</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>