On Mon, May 16, 2016 at 3:47 PM, Brandon Knope via swift-evolution < swift-evolution@swift.org> 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 <erica@ericasadun.com> 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 <bknope@me.com> 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 <erica@ericasadun.com> 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 < > swift-evolution@swift.org> 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 < > swift-evolution@swift.org>:
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
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution
_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution
_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution