On Mar 28, 2016, at 10:05 PM, Erica Sadun <[email protected]> wrote: >> >> 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. >> > > 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 agree SeeAlso seems sufficient. > 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. 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. -Chris
_______________________________________________ swift-evolution mailing list [email protected] https://lists.swift.org/mailman/listinfo/swift-evolution
