[Diagnostics] Add educational notes explaining multiple inheritance (#38253)

* Add educational notes for multiple inheritance

* Update edu note by adopting reviewer suggestions

* Update userdocs/diagnostics/multiple-class-inheritance.md

Co-authored-by: Varun Gandhi <[email protected]>

* Added Flyable protocol definition to example

* Apply suggestions from code review

Co-authored-by: Varun Gandhi <[email protected]>

* Apply suggestions from code review

Co-authored-by: Xiaodi Wu <[email protected]>

* Use consistent terminology

Co-authored-by: Xiaodi Wu <[email protected]>

* Use utensils example as suggested by review

* Update title to Multiple Inheritance

* Apply suggestions from code review

Co-authored-by: Xiaodi Wu <[email protected]>

* Rename file to match changed name

* Add more objects in protocol construction example

* Apply suggestions from code review

Co-authored-by: Xiaodi Wu <[email protected]>

Co-authored-by: Varun Gandhi <[email protected]>
Co-authored-by: Xiaodi Wu <[email protected]>

Author: 3 people

include/swift/AST/EducationalNotes.def

@@ -91,5 +91,8 @@ EDUCATIONAL_NOTES(result_builder_missing_build_either,
                   "result-builder-methods.md")
 EDUCATIONAL_NOTES(result_builder_missing_build_array,
                   "result-builder-methods.md")
-
+                  
+EDUCATIONAL_NOTES(multiple_inheritance,
+                  "multiple-inheritance.md")
+                  
 #undef EDUCATIONAL_NOTES

userdocs/diagnostics/multiple-inheritance.md

@@ -0,0 +1,37 @@
+# Multiple Inheritance
+
+In some programming languages, a class can inherit the interface of multiple base classes. Known as multiple inheritance, this feature can add significant complexity to the language and is unsupported in Swift. Instead, Swift allows composition of interfaces using protocols.
+
+Consider the following example:
+
+```swift
+protocol Utensil { 
+    var name: String { get }
+} 
+
+protocol ServingUtensil: Utensil {
+    func serve()
+} 
+
+extension ServingUtensil {
+    func serve() { /* Default implementation. */ }
+}
+
+protocol Fork: Utensil {
+    func spear()
+}
+
+protocol Spoon: Utensil {
+    func scoop()
+}
+
+struct CarvingFork: ServingUtensil, Fork { /* ... */ }
+struct Spork: Spoon, Fork { /* ... */ }
+struct Ladle: ServingUtensil, Spoon { /* ... */ }
+```
+
+Swift protocols can declare interfaces that must be implemented by each conforming type (like abstract class members in other programming languages such as C# or Java), and they can also provide overridable default implementations for those requirements in protocol extensions.
+
+When class inheritance and protocol conformances are used together, subclasses inherit protocol conformances from base classes, introducing additional complexity. For example, the default implementation of a protocol requirement not overridden in the conforming base class also cannot be overridden in any subclass ([SR-103](https://bugs.swift.org/browse/SR-103)).
+
+To learn more about defining and adopting protocols, see the [Protocols](https://docs.swift.org/swift-book/LanguageGuide/Protocols.html) section in _The Swift Programming Language_. To learn more about class inheritance, see the [Inheritance](https://docs.swift.org/swift-book/LanguageGuide/Inheritance.html) section in _The Swift Programming Language_.