ECMA-335 Augments documentation are missing some changes.

[CameronAavik]

I asked in the C# discord recently about if the ECMA-335 specification was up to date and it was mentioned that all the changes to the specification are documented here: https://github.com/dotnet/runtime/blob/master/docs/design/specs/Ecma-335-Augments.md

But it seems that this file has not been updated for the changes made as part of the work for default interface methods:
https://github.com/dotnet/runtime/blob/master/docs/design/features/default-interface-methods.md

I thought I'd raise this issue just to see if the augments document should be updated with all the ECMA-335 changes that are missing. I believe there might have also been changes needed for supporting unmanaged calling conventions?

[MichalStrehovsky]

The default interface methods document can just be pretty much directly pasted into the Augments document.

I don't know if it's the best idea to keep it all in a single markdown file. It will very quickly become a long doc nobody wants to read.

Also covariant returns are not documented. There's an implementation spec, but that's not usable as a ECMA-335 addendum.

[tannergooding]

It will very quickly become a long doc nobody wants to read.

So just like ECMA-335 😄

Joking aside, I do agree it might be nice to have an augments folder that contains the individual speclets for things like DIMs or the new calling convention changes.

[mangod9]

@davidwrighton is there a process for such ECMA doc changes?

[davidwrighton]

There is no formal process other than updating the augments document. I've already put the default interface method logic into the document some time ago, and am working on the covariant documentation now. That one is a bit more involved as the exisiting covariant document is incomplete and not precise as to the effect on the standard that the feature has. I'm also going to put a small table of contents on the top of the file as @MichalStrehovsky is right, the doc is already long and hard to read.

[KalleOlaviNiemitalo]

ECMA-335 6th Edition §II.1.8.1.2.2 says a controlled-mutability managed pointer "cannot be passed as a byref argument to a method." Now it can, for a C# in parameter; see the IL in dotnet/csharpstandard#264 (comment). Perhaps that needs changes in the verification algorithm.

[davidwrighton]

@KalleOlaviNiemitalo At this time the runtime team does not attempt to maintain the IL verification rules.