I have wanted this feature and floated it a while back. I hope we can get some traction this time but I doubt it will happen soon since additive features are tabled for a time.
On Mon, May 16, 2016 at 3:47 PM, Brandon Knope via swift-evolution < [email protected]> wrote: > I think requiring them to be in comments is what’s going to prevent their > adoption. > > My fundamental stance is that these awesome features that are required in > comments will be overlooked by people because: > • You have to remember the specific syntax > • There is no code completion which means you have to know the *exact* > syntax and spelling > > At the end of the day, Swift is a new language, and because of this, is > there a new and better way to convey information than just sticking > everything in a comment? > > With autocomplete we could get something like this: > > extension *Type,* named *Name* { > } > > This would make it much easier for people to adopt than requiring them to > remember a comment syntax. > > However, if there is no interest, I will not proceed with a proposal. > > Just my .02 > Brandon > > Where autocomplete would let you tab between naming the Type and Name > > On May 16, 2016, at 3:24 PM, Erica Sadun <[email protected]> wrote: > > Most of the Swift docs markup tech is both very new and still evolving. > I'm trying to evangelize the technology, and there are now five markup > items that actually tie into the code completion engine: > > > - > > Three new doc comment fields, namely - keyword:, - recommended: and - > recommendedover:, allow Swift users to cooperate with code completion > engine to deliver more effective code completion results. The - > keyword: field specifies concepts that are not fully manifested in > declaration names. - recommended: indicates other declarations are > preferred to the one decorated; to the contrary, - recommendedover: > indicates > the decorated declaration is preferred to those declarations whose names > are specified. > > -- E > > > On May 16, 2016, at 1:14 PM, Brandon Knope <[email protected]> wrote: > > I have never seen anyone use this. Why? Because it is relatively unknown > and not very “pretty” in my opinion. In the ideal world, everyone would > have perfectly formatted and up to date comment, but I am not convinced > this is usually the case. > > It’s good for IDE documenting, but: > • Online tutorials do NOT use this in code samples, keeping it from being > widely known (and because it looks ugly next to their sample and makes it > look more verbose) > • It really does not look nice with the language. It seems like IDE magic > • What about people writing in a text editor or not in Xcode? If they do > not get a benefit out of // MARK: or /// - Keyword: why would they use it? > > And a quick read of Matthew’s proposal tells me that it may be beneficial > to be able to refer to the name of an extension in the future. I am still > reading through his proposal but that’s what I took from it with a quick > look. > > > Brandon > > On May 16, 2016, at 3:08 PM, Erica Sadun <[email protected]> wrote: > > Or better yet, the 'Keyword" token offers searchable content that can > relate one extension to the other. > > /// - Keyword: Lifecycle extension > > -- Erica > > > On May 16, 2016, at 11:33 AM, Michael Peternell via swift-evolution < > [email protected]> wrote: > > Why not just use a (documentation) comment? > > /// The Lifecycle extension: > extension ViewController { > ... > > -Michael > > Am 16.05.2016 um 18:26 schrieb Brandon Knope via swift-evolution < > [email protected]>: > > I like to separate methods into their own logical extensions so similar > methods are grouped together. I do this mostly with Cocoa Touch where I > like all view life cycle methods to be in the same extension: > > extension ViewController { > override func viewDidLoad() { > } > > override func viewWillAppear(animated: Bool) { > } > > override func viewDidDisappear(animated: Bool) { > } > } > > You can document this somewhat by adding a MARK comment: > > // MARK: Lifecylce > extension ViewController { > override func viewDidLoad() { > } > > override func viewWillAppear(animated: Bool) { > } > > override func viewDidDisappear(animated: Bool) { > } > } > > What if we made this more self-documenting by elevating this to a language > feature? > > extension ViewController named Lifecycle { > override func viewDidLoad() { > } > > override func viewWillAppear(animated: Bool) { > } > > override func viewDidDisappear(animated: Bool) { > } > } > > Other ways: > extension named Lifecycle ViewController { } > extension named “View Lifecycle" ViewController { } > extension ViewController named “Multi word description” { } > > > For now, this is purely a documenting feature (i.e. Can’t refer to the > extension name dynamically or statically in actual code). I think it plays > much more naturally with Swift than requiring this to be in the comments > and would work across all IDEs and make it easier for people to find a > specific extension as well as making their code more self documenting. > > Any thoughts? > > Thanks, > Brandon > > > > _______________________________________________ > swift-evolution mailing list > [email protected] > https://lists.swift.org/mailman/listinfo/swift-evolution > > > _______________________________________________ > swift-evolution mailing list > [email protected] > https://lists.swift.org/mailman/listinfo/swift-evolution > > > > > > > _______________________________________________ > swift-evolution mailing list > [email protected] > https://lists.swift.org/mailman/listinfo/swift-evolution > >
_______________________________________________ swift-evolution mailing list [email protected] https://lists.swift.org/mailman/listinfo/swift-evolution
