Figuring out what you get for free

If you look at the source for Sequence <swift/Sequence.swift at main · apple/swift · GitHub, you can see that the protocol declares a ton of methods and properties; but in fact, all you need to provide is Element, Iterator and makeIterator. The rest comes for free, but can be specialized.

Of course, I don't want to work more than I need to. However, I find that I'm having trouble figuring out what I get for free when I implement a protocol. In principle, I like conditional conformances and synthesized implementation of protocol methods, but I find that they both make it harder to figure out what I need to implement, and what are going to be the performance characteristics of methods that I choose to not implement.

I feel like this is perceived to be a problem by a lot of other people. Is there anything that can make it easier to figure out what you get for free?

Félix

However, I find that I'm having trouble figuring out what I get for free when I implement a protocol. In principle, I like conditional conformances and synthesized implementation of protocol methods, but I find that they both make it harder to figure out what I need to implement, and what are going to be the performance characteristics of methods that I choose to not implement.

If you're thinking specifically about the standard library, the documentation for protocols like Sequence shows whether a member is required, and whether it provides a default implementation.

https://developer.apple.com/documentation/swift/sequence#2923865

Have you noticed that before, or is it still tricky to find requirements given the presentation?

-Kyle

i think in general the API docs could be organized in a more helpful way.

···

On Fri, Sep 15, 2017 at 3:30 PM, Kyle Murray via swift-evolution < swift-evolution@swift.org> wrote:

However, I find that I'm having trouble figuring out what I get for free
when I implement a protocol. In principle, I like conditional conformances
and synthesized implementation of protocol methods, but I find that they
both make it harder to figure out what I need to implement, and what are
going to be the performance characteristics of methods that I choose to not
implement.

If you're thinking specifically about the standard library, the
documentation for protocols like Sequence shows whether a member is
required, and whether it provides a default implementation.

Apple Developer Documentation

Have you noticed that before, or is it still tricky to find requirements
given the presentation?

-Kyle

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

I found that for Sequence, but Sequence is far from the only protocol with default implementations, and not all of them have maintainers willing to write and update documentation to the degree that Apple will.

Félix

···

Le 14 sept. 2017 à 15:10, Kyle Murray <kyle_murray@apple.com> a écrit :

However, I find that I'm having trouble figuring out what I get for free when I implement a protocol. In principle, I like conditional conformances and synthesized implementation of protocol methods, but I find that they both make it harder to figure out what I need to implement, and what are going to be the performance characteristics of methods that I choose to not implement.

If you're thinking specifically about the standard library, the documentation for protocols like Sequence shows whether a member is required, and whether it provides a default implementation.

Apple Developer Documentation

Have you noticed that before, or is it still tricky to find requirements given the presentation?

-Kyle

How I do it is like this:

1. Make a dummy struct (or class) that claim conformance to a protocol:

struct Z: Collection {
}

2. Compiling, then deciphering the errors tells me that type deduction doesn't work for associated type `Index` because there is no subscript. So I add one:

struct Z: Collection {
  subscript (index: Int) -> Int {
    get { return index }
  }
}

3. Compiling again, I now get a suggestion (fixit) telling me to add `startIndex` and `endIndex`. I add the suggested code:

struct Z: Collection {
  var startIndex: Int

  var endIndex: Int

  subscript (index: Int) -> Int {
    get { return index }
  }
}

4. Compiling again, I get another suggestion (fixit) telling me I'm missing `index(after:)`. I add it and write an implementation inside the braces. And here I am:

struct Z: Collection {
  func index(after i: Int) -> Int {
    return i + 1
  }

  var startIndex: Int

  var endIndex: Int

  subscript (index: Int) -> Int {
    get { return index }
  }
}

5. And now it compiles. Hurray!

I made a collection type and did not have to read any documentation at all. The hardest step is the first one where you have to figure out how to make deduction work for the associated types based on the error messages.

···

Le 17 sept. 2017 à 18:00, Félix Cloutier via swift-evolution <swift-evolution@swift.org <mailto:swift-evolution@swift.org>> a écrit :

I found that for Sequence, but Sequence is far from the only protocol with default implementations, and not all of them have maintainers willing to write and update documentation to the degree that Apple will.

--
Michel Fortin
https://michelf.ca <https://michelf.ca/&gt;

--
Michel Fortin
https://michelf.ca

I guess the question is, "Do we want this to be the process we expect of
and explain to newcomers?"

···

On Sun, Sep 17, 2017 at 7:32 PM, Michel Fortin via swift-evolution < swift-evolution@swift.org> wrote:

Le 17 sept. 2017 à 18:00, Félix Cloutier via swift-evolution < > swift-evolution@swift.org> a écrit :

I found that for Sequence, but Sequence is far from the only protocol with
default implementations, and not all of them have maintainers willing to
write and update documentation to the degree that Apple will.

How I do it is like this:

1. Make a dummy struct (or class) that claim conformance to a protocol:

struct Z: Collection {
}

2. Compiling, then deciphering the errors tells me that type deduction
doesn't work for associated type `Index` because there is no subscript. So
I add one:

struct Z: Collection {
subscript (index: Int) -> Int {
get { return index }
}
}

3. Compiling again, I now get a suggestion (fixit) telling me to add
`startIndex` and `endIndex`. I add the suggested code:

struct Z: Collection {
var startIndex: Int

var endIndex: Int

subscript (index: Int) -> Int {
get { return index }
}
}

4. Compiling again, I get another suggestion (fixit) telling me I'm
missing `index(after:)`. I add it and write an implementation inside the
braces. And here I am:

struct Z: Collection {
func index(after i: Int) -> Int {
return i + 1
}

var startIndex: Int

var endIndex: Int

subscript (index: Int) -> Int {
get { return index }
}
}

5. And now it compiles. Hurray!

I made a collection type and did not have to read any documentation at
all. The hardest step is the first one where you have to figure out how to
make deduction work for the associated types based on the error messages.

--
Michel Fortin
https://michelf.ca

--
Michel Fortin
https://michelf.ca

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

It could certainly be improved:

- In step 2, the compiler could propose a fixit for subscript where the unknown associated type is replaced by a placeholder.
- Fixits from steps 2, 3, and 4 should be combined together as a single fixit.

And with this: you add the conformance to your type, Xcode automatically suggest everything you need to add, and you then add it in one click.

···

Le 17 sept. 2017 à 22:13, T.J. Usiyan <griotspeak@gmail.com> a écrit :

I guess the question is, "Do we want this to be the process we expect of and explain to newcomers?"

On Sun, Sep 17, 2017 at 7:32 PM, Michel Fortin via swift-evolution <swift-evolution@swift.org <mailto:swift-evolution@swift.org>> wrote:

Le 17 sept. 2017 à 18:00, Félix Cloutier via swift-evolution <swift-evolution@swift.org <mailto:swift-evolution@swift.org>> a écrit :

I found that for Sequence, but Sequence is far from the only protocol with default implementations, and not all of them have maintainers willing to write and update documentation to the degree that Apple will.

How I do it is like this:

1. Make a dummy struct (or class) that claim conformance to a protocol:

struct Z: Collection {
}

2. Compiling, then deciphering the errors tells me that type deduction doesn't work for associated type `Index` because there is no subscript. So I add one:

struct Z: Collection {
  subscript (index: Int) -> Int {
    get { return index }
  }
}

3. Compiling again, I now get a suggestion (fixit) telling me to add `startIndex` and `endIndex`. I add the suggested code:

struct Z: Collection {
  var startIndex: Int

  var endIndex: Int

  subscript (index: Int) -> Int {
    get { return index }
  }
}

4. Compiling again, I get another suggestion (fixit) telling me I'm missing `index(after:)`. I add it and write an implementation inside the braces. And here I am:

struct Z: Collection {
  func index(after i: Int) -> Int {
    return i + 1
  }

  var startIndex: Int

  var endIndex: Int

  subscript (index: Int) -> Int {
    get { return index }
  }
}

5. And now it compiles. Hurray!

I made a collection type and did not have to read any documentation at all. The hardest step is the first one where you have to figure out how to make deduction work for the associated types based on the error messages.

--
Michel Fortin
https://michelf.ca <https://michelf.ca/&gt;

--
Michel Fortin
https://michelf.ca <https://michelf.ca/&gt;

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

--
Michel Fortin
https://michelf.ca

- In step 2, the compiler could propose a fixit for subscript where the unknown associated type is replaced by a placeholder.
- Fixits from steps 2, 3, and 4 should be combined together as a single fixit.

Would be nice indeed. But I too believe that we could make it way easier for newcomers if the documentation was better organised. That would solve the problem for most unless all the stdlib, which is what newcomers are most likely to conform to.

To be clear, I find the stdlib already fairly well-documented. I think that the problem is more important for types from projects that are unlikely to get good documentation.

···

Le 17 sept. 2017 à 23:43, Dimitri Racordon via swift-evolution <swift-evolution@swift.org> a écrit :

- In step 2, the compiler could propose a fixit for subscript where the unknown associated type is replaced by a placeholder.
- Fixits from steps 2, 3, and 4 should be combined together as a single fixit.

Would be nice indeed. But I too believe that we could make it way easier for newcomers if the documentation was better organised. That would solve the problem for most unless all the stdlib, which is what newcomers are most likely to conform to.

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