Inherit doc comments from default implementations of inherited protocols

[ahoppen]

For example when we have

protocol BaseProtocol {}

extension BaseProtocol {
  /// Say hello
  func hello() { }
}
struct MyStruct: BaseProtocol {
  func hello() {}
}

Then MyStruct.hello should inherit the doc comment from the implementation of BaseProtocol.hello. Currently no doc comment is associated with MyStruct.hello.

rdar://126240546

---

The changes in offsets in the test cases is because init(rawValue:) now inherits the doc comment of RawRepresentable, which shifts the lines in generated interfaces around.

[bnbarham]

Suggested change

	/// Check if there is an inherited protocol that has a default implementaiton
	/// Check if there is an inherited protocol that has a default implementation

[bnbarham]

Could add a test for the case where there is both a requirement and a default

[ahoppen]

@swift-ci Please smoke test

[hamishknight]

What if VD is defined in an extension? Do we want to support that?

[ahoppen]

We do with the lines below, right?

https://github.com/apple/swift/pull/73066/files#diff-ff85ad3908ab33036e814561ae7b5cec9f0be34b4de5106b989957b2d5ee5afeR434-R436

[hamishknight]

That only handles protocol extensions, right? I was thinking of e.g a struct extension

[ahoppen]

@QuietMisdreavus This comments seems to imply the exact opposite of what I want to achieve in this PR. Is there any reason why we didn’t want to inherit documentation from extensions?

For context, the concrete example I want to fix with this PR is that this implementation of _ArrayProtocol.filter https://github.com/apple/swift/blob/c531f2914fda0b84d8af091a0081799101f76d9b/stdlib/public/core/ArrayType.swift#L73-L78 should inherit the documentation from the documentation of Sequence.filter, which is implemented in an extension https://github.com/apple/swift/blob/5df0f053d95c1143ac34ac88faafdfa3902a3224/stdlib/public/core/Sequence.swift#L717-L739

[QuietMisdreavus]

cc @franklinsch (and possibly also @bitjammer for the underlying discussion of inheriting docs in the first place)

I think it should respect the presence of the -skip-inherited-docs flag, but otherwise i don't remember off the top of my head.

[ahoppen]

I think we already respect the -skip-inherited-docs flag because we’re not calling into getDocCommentProvidingDecl if it is set and this PR only modifies getDocCommentProvidingDecl

https://github.com/apple/swift/blob/9fdb0e79e2dab72fdc01f8fa50d9cc249a48a5a0/lib/SymbolGraphGen/Symbol.cpp#L359-L365

[hamishknight]

Should this be the other way around? e.g allowing:

protocol P {}
extension P {
  /// hello
  func foo() -> Int? { 0 }
}
struct S: P {
  func foo() -> Int { 0 }
}

But not:

protocol P {}
extension P {
  /// hello
  func foo() -> Int { 0 }
}
struct S: P {
  func foo() -> Int? { 0 }
}

Not that these are really overrides anyway, but if we want similar type-matching rules, then I think it makes sense to flip the ordering.

[ahoppen]

Oh, yes. I thought that I had this case covered with the throws case but apparently throws works either way 🤷🏽

[hamishknight]

Thought of a couple more edge cases :)

1. static mismatch

protocol P {}
extension P {
  /// hello
  static func foo() {}
}
struct S: P {
  func foo() {}
}
func bar(_ x: S) {
  x.foo()
}

2. enum case matching a function (if we want this to work it would need to be a static function)

protocol P {}
extension P {
  /// hello
  func foo(_ x: Int) -> E { .foo(0) }
}

enum E: P {
  case foo(Int)
}

func bar(_ x: E) {
  E.foo(0)
}

3. this is quite silly, but technically this would match:

class C {
  /// hello
  struct foo {}
}
class D: C {
  var foo: C.foo.Type { C.foo.self }
}

func bar(_ x: D) {
  let y = x.foo
}

[ahoppen]

Good cases, thanks. Case 3 does inherit but I decided to not care and not add a test case for it. If it broke, I don’t think we would care.

[hamishknight]

Wonder if we ought to have a utility for removing the curried self, could be used in a couple of other places:

https://github.com/apple/swift/blob/15fd443be60cfb52852c853c4fa0d6a1622ada10/lib/Sema/TypeCheckProtocol.cpp#L4894-L4896

https://github.com/apple/swift/blob/15fd443be60cfb52852c853c4fa0d6a1622ada10/lib/Sema/AssociatedTypeInference.cpp#L1990-L1993

https://github.com/apple/swift/blob/15fd443be60cfb52852c853c4fa0d6a1622ada10/lib/AST/Decl.cpp#L4937-L4939

[ahoppen]

@swift-ci Please smoke test

[ahoppen]

@swift-ci Please smoke test

[slavapestov]

This is just duplicating logic in the witness checker. Default witnesses are recorded in the ProtocolDecl.

See TypeChecker::inferDefaultWitnesses() and ProtocolDecl::getDefaultWitness().

[ahoppen]

That’s not sufficient though. We aren’t dealing with protocol requirements here, just default methods on a protocol.

For example in the following test, InheritedProtocol.hello() needs to inherit the documentation from BaseProtocol.hello but there is no protocol requirement that hello() can be a witness for. Any suggestion of how to implement that without my implementation?

protocol BaseProtocol {}
extension BaseProtocol {
  /// Say hello
  func hello() { }
}

protocol InheritedProtocol: BaseProtocol {}
extension InheritedProtocol {
  func hello() { }
}

[ahoppen]

@swift-ci Please smoke test Linux