[Proposal]: Implementation specific documentation

[BillWagner]

Implementation specific documentation

• [x] Proposed
• [ ] Prototype: Not Started
• [ ] Implementation: Not Started
• [ ] Specification: Not Started

Summary

In LDM, we've wanted to be precise and complete on the behavior of new features. This means that feature speclets often include more implementation details than we might want in the official language specification. We want a roadmap for ourselves to document this behavior, and guidelines on what should be in the language specification vs. roslyn-specific documents.

For example, the roslyn repo already includes a document for Specification deviations.

Motivation

We want to clearly define all supported behavior, but we also want to keep the language specification "clean" regarding many implementation details.

Detailed design

There should be four different documents in the roslyn repo, and the published on Microsoft Learn in the language specification area. Most are required in the section of the specification on Portability issues

• The existing Specification deviations document. This document describes roslyn-specific compiler behavior that deviates from normative language in the C# language specification. Note that this document is incomplete.
• An article that describes Implementation defined behavior. The specification defines a number of behaviors that should be defined for the roslyn implementation. We don't have that article at this time.
• An article that describes behavior supported by roslyn, where the language specification doesn't require certain behavior. An example is that roslyn now defines 1 as the value of a bool that is true. The language specification only requires a value be "distinct from zero.".
• An article that describes any behavior defined by roslyn where the language specification leaves the behavior as undefined. This could be combined with the previous article.

Drawbacks

It is more work.

Alternatives

We could require all the implementation behavior to be part of the language specification.

Unresolved questions

What behaviors that aren't required by the standard are supported by roslyn?

Design meetings

This issue was raised on Jan 31. Notes aren't yet available.

[BillWagner]

@CyrusNajmabadi Does this capture your thoughts on Wednesday?

[BillWagner]

Another area for discussion on this issue:

How do we want to handle spec deviations where the rolsyn compiler behavior enables code constructs that the Standard prohibits.

One example is how roslyn handles reference parameters for iterator methods and async methods

In both clauses, the standard states:

When a function member is implemented using an iterator block (or async method), it is a compile-time error for the formal parameter list of the function member to specify any in, out, or ref parameters, or any parameter of a ref struct type.

However, the roslyn implementation allows this as long as that parameter isn't captured by the iterator or async state machine.