> On Mar 28, 2016, at 10:25 PM, Chris Lattner <[email protected]> wrote: > > >> On Mar 28, 2016, at 5:34 PM, Erica Sadun via swift-evolution >> <[email protected] <mailto:[email protected]>> 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
_______________________________________________ swift-evolution mailing list [email protected] https://lists.swift.org/mailman/listinfo/swift-evolution
