Idea: Named extensions

Brandon_Knope · May 16, 2016, 4:26pm

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

Michael_Peternell · May 16, 2016, 5:33pm

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

Erica_Sadun · May 16, 2016, 7:08pm

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

Erica_Sadun · May 16, 2016, 7:24pm

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

anandabits · May 16, 2016, 6:58pm

Why not just use a (documentation) comment?

/// The Lifecycle extension:
extension ViewController {

There have been discussions about possibly allowing extensions to have stored properties in the future. If that comes to pass it may well be useful for extensions to have a name that can be used to refer to the extension during initialization. I discussed possible syntax for that in my draft proposal for partial initializers (which I tabled for Swift 3, but may revive in the future).

···

Sent from my iPad

On May 16, 2016, at 12:33 PM, Michael Peternell via swift-evolution <swift-evolution@swift.org> wrote:

...

-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

anandabits · May 16, 2016, 7:02pm

Do you have a link to your proposal?

The part relevant to this thread is in the section “Interactions with other features”

github.com

anandabits/swift-evolution/blob/partial-initializers/proposals/NNNN-partial-initializers.md

# Partial Initializers

* Proposal: [SE-NNNN](https://github.com/apple/swift-evolution/blob/master/proposals/NNNN-partial-initializers.md)
* Author(s): [Matthew Johnson](https://github.com/anandabits)
* Status: **Awaiting review**
* Review manager: TBD

## Introduction

This proposal introduces partial initializers and initialization methods.  They perform part, but not all, of phase one initialization for a type.  They can be called by designated initializers or other partial initializers.  Initialization methods may also be called like normal methods post-initialization, but may only write to `var` properties.

Swift-evolution thread: [Proposal Draft: partial initializers](https://lists.swift.org/pipermail/swift-evolution/Week-of-Mon-20160104/006179.html)

## Motivation

Swift currently requires all initialization assigments to happen in the main body of a designated initializer.  Swift does this for a great reason: to enforce rules enabling definitive and safe initiailization.  

Unfortunately this means that we are **required** to separate any computation we wish to factor out from the initialization assignments.  This may be a good idea in some cases, but in others it is inconvenient and leads to less readable code.  

Lifting this limitation while still guaranteeing definitive and safe initialization is very desirable.  It will allow us to better factor out common behavior and make our code more readable.  It will also lay a foundation that could be built upon by future language features.

This file has been truncated. show original

···

On May 16, 2016, at 1:59 PM, Brandon Knope <bknope@me.com> wrote:

Thanks,
Brandon

On May 16, 2016, at 2:58 PM, Matthew Johnson <matthew@anandabits.com <mailto:matthew@anandabits.com>> wrote:

Sent from my iPad

On May 16, 2016, at 12:33 PM, Michael Peternell via swift-evolution <swift-evolution@swift.org <mailto:swift-evolution@swift.org>> wrote:

Why not just use a (documentation) comment?

/// The Lifecycle extension:
extension ViewController {

There have been discussions about possibly allowing extensions to have stored properties in the future. If that comes to pass it may well be useful for extensions to have a name that can be used to refer to the extension during initialization. I discussed possible syntax for that in my draft proposal for partial initializers (which I tabled for Swift 3, but may revive in the future).

...

-Michael

Am 16.05.2016 um 18:26 schrieb Brandon Knope via swift-evolution <swift-evolution@swift.org <mailto: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 <mailto:swift-evolution@swift.org>
https://lists.swift.org/mailman/listinfo/swift-evolution

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org <mailto:swift-evolution@swift.org>
https://lists.swift.org/mailman/listinfo/swift-evolution

Brandon_Knope · May 16, 2016, 6:17pm

Because to me this seems too indirect and not explicit enough.

I think doing it explicitly:
• Makes your intent much clearer
• Forces you to think about not throwing everything into one big extension (i.e. somewhat more binding than a comment that can easily be looked over)
• Shows that it’s a first class feature of the language, encouraging everyone to use it. Makes it easier to see in tutorials and code samples as it reads more natural than // MARK:
• Does not feel hacky with a comment (and comments are easy to forget to update, making them possibly outdated)
• Looks better than having to use comments (imo)

It is reminiscent of named categories in Objective-C where I found the names to be quite self documenting and clearer.

To me it just feels like a natural extension…onto extensions.

In the end, there is nothing with wrong using comments, but it feels a little more archaic to me.

For a little contrived example:

In the swift guide, there is an example like this:

extension Double {
    var km: Double { return self * 1_000.0 }
    var m: Double { return self }
    var cm: Double { return self / 100.0 }
    var mm: Double { return self / 1_000.0 }
    var ft: Double { return self / 3.28084 }
}

• It is clear what the intent is here: to provide methods to convert a double into other units
• Why not make this intent explicit? Otherwise it is too easy to add unrelated methods:

extension Double {
    var km: Double { return self * 1_000.0 }
    var m: Double { return self }
    var cm: Double { return self / 100.0 }
    var mm: Double { return self / 1_000.0 }
    var ft: Double { return self / 3.28084 }

var squared: Double { return self * self } //This computed property is unlike the others, introducing some bloat to this extension
}

Something like this is more “explicit”

named Unit Conversion extension Double {
    var km: Double { return self * 1_000.0 }
    var m: Double { return self }
    var cm: Double { return self / 100.0 }
    var mm: Double { return self / 1_000.0 }
    var ft: Double { return self / 3.28084 }

//var squared: Double { return self * self } It is not clear that this method does not fit with the others and should be moved
}

There is somewhat of a contract here where everything in this extension is a kind of conversion. Anyone could still add whatever they want to this extension because this is really just a form of documentation and it has no idea whether what you are adding fits with the name, but I find it to be a little more binding and requires the programmer to ask themselves if their addition fits with the rest of the extension.

The obvious question again is: Why not just use a comment to document it? My answer to this is: I don’t think most use comments to signify their intent of the extension. They either do not know it exists or do not find it worthwhile. I think making it explicit to the language gives people incentive to use it. It would be included in more code samples because it is a natural part of the extension and not “just another comment” to skim by, meaning more people would know it exists and use it more.

Also, no // MARK: Bar syntax needs to be remembered. MARK: is also less pretty and harder to type

More formatting options:

named Unit Conversion
extension Double {
}

extension Double, named Unit Conversion { //avoids requiring “ "
}

At the end of the day, how many developers know and remember to use // MARK:? I think this feature with code completion would promote much wider adoption.

Brandon

···

On May 16, 2016, at 1:33 PM, Michael Peternell <michael.peternell@gmx.at> 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

Brandon_Knope · May 16, 2016, 6:59pm

Do you have a link to your proposal?

Thanks,
Brandon

···

On May 16, 2016, at 2:58 PM, Matthew Johnson <matthew@anandabits.com> wrote:

Sent from my iPad

On May 16, 2016, at 12:33 PM, Michael Peternell via swift-evolution <swift-evolution@swift.org <mailto:swift-evolution@swift.org>> wrote:

Why not just use a (documentation) comment?

/// The Lifecycle extension:
extension ViewController {

There have been discussions about possibly allowing extensions to have stored properties in the future. If that comes to pass it may well be useful for extensions to have a name that can be used to refer to the extension during initialization. I discussed possible syntax for that in my draft proposal for partial initializers (which I tabled for Swift 3, but may revive in the future).

...

-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 <mailto:swift-evolution@swift.org>
https://lists.swift.org/mailman/listinfo/swift-evolution

Brandon_Knope · May 16, 2016, 7:14pm

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

Brandon_Knope · May 16, 2016, 7:47pm

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 <mailto: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 <mailto: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 <mailto: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 <mailto: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 <mailto:swift-evolution@swift.org>
https://lists.swift.org/mailman/listinfo/swift-evolution

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org <mailto:swift-evolution@swift.org>
https://lists.swift.org/mailman/listinfo/swift-evolution

griotspeak · May 16, 2016, 8:25pm

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 < 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

Brandon_Knope · May 16, 2016, 8:27pm

Here is an attempt to express myself better :)

Objective-C to Swift category to extension conversion loss of descriptive name

Objective-C category:
@interface NSAttributedString (NSAttributedStringDocumentFormats)
// Methods initializing the receiver contents with an external document data. options specify document attributes for interpreting the document contents. NSDocumentTypeDocumentAttribute, NSCharacterEncodingDocumentAttribute, and NSDefaultAttributesDocumentAttribute are supported options key. When they are not specified, these methods will examine the data and do their best to detect the appropriate attributes. If dict is non-NULL, it will return a dictionary with various document-wide attributes accessible via NS...DocumentAttribute keys.
- (nullable instancetype)initWithURL:(NSURL *)url options:(NSDictionary<NSString *, id> *)options documentAttributes:(NSDictionary<NSString *, id> * __nullable * __nullable)dict error:(NSError **)error NS_AVAILABLE(10_11, 9_0);

...
@end

Translated Swift extension:
extension NSAttributedString {
    // Methods initializing the receiver contents with an external document data. options specify document attributes for interpreting the document contents. NSDocumentTypeDocumentAttribute, NSCharacterEncodingDocumentAttribute, and NSDefaultAttributesDocumentAttribute are supported options key. When they are not specified, these methods will examine the data and do their best to detect the appropriate attributes. If dict is non-NULL, it will return a dictionary with various document-wide attributes accessible via NS...DocumentAttribute keys.
    @available(iOS 9.0, *)
    public init(URL url: NSURL, options: [String : AnyObject], documentAttributes dict: AutoreleasingUnsafeMutablePointer<NSDictionary?>) throws
...
}

The self-documenting name of the category is lost when imported in Swift. Some categories have no outward comment describing it because they seem to rely on the category name. For example, this one *does* have a comment describing it that is imported into swift:

Objective-C
/************************ Attribute fixing ************************/

@interface NSMutableAttributedString (NSAttributedStringAttributeFixing)

@end

Swift:
/************************ Attribute fixing ************************/
extension NSMutableAttributedString {

}

Again, the comment is not enforced by the compiler and is a style choice. Names on categories are enforced (except for a class’s private () category)

One moonshot: Are extension’s an implementation detail?

Here is the generated interface for a simple View Controller

internal class ViewController : UIViewController {

override internal func viewDidLoad()

override internal func didReceiveMemoryWarning()
}

extension ViewController {

internal func test()
}

Theoretically, if we had named extensions:

extension ViewController named Test {
internal func test() {

}
}

could be translated to:

internal class ViewController : UIViewController {

override internal func viewDidLoad()

override internal func didReceiveMemoryWarning()

Test:
internal func test()

}

I am not sure if this behavior would be truly desired, but it would allow the methods to remained group under a comment or a header of some sort.

//Phew
Brandon

···

On May 16, 2016, at 4:25 PM, T.J. Usiyan <griotspeak@gmail.com> wrote:

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 <swift-evolution@swift.org <mailto: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 <mailto: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 <mailto: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 <mailto: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 <mailto: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 <mailto: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 <mailto:swift-evolution@swift.org>
https://lists.swift.org/mailman/listinfo/swift-evolution

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org <mailto:swift-evolution@swift.org>
https://lists.swift.org/mailman/listinfo/swift-evolution

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org <mailto:swift-evolution@swift.org>
https://lists.swift.org/mailman/listinfo/swift-evolution

Brandon_Knope · May 16, 2016, 8:28pm

Ya I didn’t see that email until after I wrote it up. If it does gain traction, I wouldn’t mind writing a proposal and tabling it for now.

Would just like to see some discussion on it, but I don’t want to detract from the current goals!

Brandon

···

On May 16, 2016, at 4:25 PM, T.J. Usiyan <griotspeak@gmail.com> wrote:

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 <swift-evolution@swift.org <mailto: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 <mailto: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 <mailto: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 <mailto: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 <mailto: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 <mailto: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 <mailto:swift-evolution@swift.org>
https://lists.swift.org/mailman/listinfo/swift-evolution

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org <mailto:swift-evolution@swift.org>
https://lists.swift.org/mailman/listinfo/swift-evolution

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org <mailto:swift-evolution@swift.org>
https://lists.swift.org/mailman/listinfo/swift-evolution