dotnet/csharplang

[Proposal]: Edit speclets to distinguish features already delivered from potential future enhancements

BillWagner opened this issue · 4 comments

BillWagner commented

We've been publishing the feature speclets on Learn so that customers can easily access the detailed information about new features.

There have been a few comments from readers that are confused because the speclets include specification language for features that haven't been implemented yet. For example:

There are likely others.

One fix would be to make the following edits:

  1. Separate out sections that haven't been implemented into new proposals in the Proposals.
  2. Link to the new "proposed additions" speclet from the existing specs to provide a roadmap for future work. That link would be an absolute GitHub link, so that readers on Learn would be redirected to GitHub. That would be a signal that it's a future enhancement.

That would benefit Learn readers, and provide a clear distinction for designers and the compiler team on what behavior has been implemented, and what behavior is still in a proposed state.

LDM should weigh in on this before editing the docs.

333fred commented

Another part to consider is the sections of the specs that call out invalid scenarios: I've had several questions on some of the DIMs examples of what doesn't work from people just copy/pasting examples.

  • 👍1
KathleenDollard commented

@333fred We might want a docs feature on this. I'd love to see some different visual appearance when it is an example of what not to do, either because it won't work or it's just a terrible idea.

That is probably a docs infrastructure issue. @BillWagner should we open one?

jcouv commented

Found another one: the inline-arrays spec suggests that inline array types can be initialized from a collection expression, but that's not supported.
https://github.com/dotnet/csharplang/blob/main/proposals/csharp-12.0/inline-arrays.md#collection-literals

FYI @AlekseyTs @cston

  • 👍2