Given the following API definition:
```cs
[Protocol]
public interface Protocol {
[Abstract]
[Export ("requiredMethod")]
void RequiredMethod ();
[Export ("optionalMethod")]
void OptionalMethod ();
}
```
we're now binding it like this:
```cs
[Protocol ("Protocol")]
public interface IProtocol : INativeObject {
[RequiredMember]
[Export ("requiredMethod")]
public void RequiredMethod () { /* default implementation */ }
[OptionalMember]
[Export ("optionalMethod")]
public void OptionalMethod () { /* default implementation */ }
}
```
The main difference from before is that the only difference between required
and optional members is the [RequiredMember]/[OptionalMember] attributes.
This has one major advantage: it's now possible to switch a member from being
required to being optional, or vice versa, without breaking neither source nor
binary compatibility.
It also improves intellisense for optional members. In the past optional
members were implemented using extension methods, which were not very
discoverable when you were supposed to implement a protocol in your own class.
The main downside is that the C# compiler won't enforce developers to
implement required protocol members (which is a necessary side effect of the
fact that we want to be able to switch members between being required and
optional without breaking compatibility). If this turns out to be a problem,
we can implement a custom source analyzer and/or linker step that detects
missing implementations and issue warnings/errors.
This PR also:
* Adds numerous tests.
* Updates the requiredness of a few members in Metal to test that it works as
expected.
* Adds documentation.
* Handles numerous corner cases, which are documented in code and docs.
This PR is probably best reviewed commit-by-commit.
Fixes https://github.com/xamarin/xamarin-macios/issues/13294.
e9d59d5f58