From 9e1bbc12036f924bc1f59c58412c780969cc5cd2 Mon Sep 17 00:00:00 2001 From: Erik Ernst Date: Mon, 10 Feb 2020 11:31:44 +0000 Subject: [PATCH] Ensuring that every feature spec in SDK is marked as background material A couple of feature specs did not explicitly say that they are now background material and normative language should be found in specific other places. This CL does that. It also makes the README.md even more explicit in order to make the same point. Change-Id: I79cbd86a662faf478ce41c01e09c5f32a3f03cd3 Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/134824 Reviewed-by: Lasse R.H. Nielsen Commit-Queue: Erik Ernst --- docs/language/informal/README.md | 38 ++++++++++--------- .../informal/extreme-upper-lower-bounds.md | 2 +- docs/language/informal/implicit-creation.md | 2 +- .../language/informal/instantiate-to-bound.md | 2 +- 4 files changed, 24 insertions(+), 20 deletions(-) diff --git a/docs/language/informal/README.md b/docs/language/informal/README.md index cd6c9f0b0f8..ae9b49e0cb3 100644 --- a/docs/language/informal/README.md +++ b/docs/language/informal/README.md @@ -1,24 +1,16 @@ -### This directory contains feature specifications. +## Background material about features -**Note**: This directory contains older feature specifications, new ones -should be submitted to the language repository -[here](https://github.com/dart-lang/language). +This directory contains background material only. Consult the +[language specification](https://dart.dev/guides/language/spec) +and the +[language repository](https://github.com/dart-lang/language) +for current information. -The existing feature specifications in this directory will have their status -updated as we proceed, and in particular each of them will become 'background' -material as it is integrated into the language specification. When all feature -specifications in this directory (that is, all other files than this one) have -become background material, this directory will serve only as documentation for -the process whereby each feature was designed and the associated motivation. - -That said, the following section contains a few words about what a feature -specification is, and how it can be used. - -### What is a Feature Specification? +### What is a feature specification? In order to move faster and get better feedback, we implement and iterate on -language changes before the full official specification has been written. Still, -the implementers need *something* to go on. +language changes before the full official specification has been written. +Still, the implementers need *something* to go on. For that, the language team writes _feature specifications_. These are intended to be precise enough for a good faith implementer to correctly @@ -27,3 +19,15 @@ of a feature specification is integrated into the language specification we expect the extra processing to give rise to additional clarifications and corrections, which means that a feature specification is expected to be _nearly_ as complete and correct as the language specification. + +### Feature specifications in this directory + +This directory contains older feature specifications, newer ones can be +found in, respectively should be submitted to, the language repository +[here](https://github.com/dart-lang/language). + +The status of every feature specification in this directory is that it is +background material, and the contents has been integrated into the language +specification. Consequently, these feature specifications can only be used +as a source of informal background information. Precise rules about the +features should be looked up in the language specification. diff --git a/docs/language/informal/extreme-upper-lower-bounds.md b/docs/language/informal/extreme-upper-lower-bounds.md index 982dc4d4abe..a2e7c69a860 100644 --- a/docs/language/informal/extreme-upper-lower-bounds.md +++ b/docs/language/informal/extreme-upper-lower-bounds.md @@ -2,7 +2,7 @@ **Owner**: eernst@ -**Status**: Implemented. +**Status**: Background material, normative language now in dartLangSpec.tex. **Version**: 0.2 (2018-05-22) diff --git a/docs/language/informal/implicit-creation.md b/docs/language/informal/implicit-creation.md index dfa46e1e168..903ff409458 100644 --- a/docs/language/informal/implicit-creation.md +++ b/docs/language/informal/implicit-creation.md @@ -4,7 +4,7 @@ Author: eernst@. Version: 0.7 (2018-04-10) -Status: Implemented. +Status: Background material, normative language now in dartLangSpec.tex. **This document** is an informal specification of the *implicit creation* feature. **The feature** adds support for omitting some occurrences of the diff --git a/docs/language/informal/instantiate-to-bound.md b/docs/language/informal/instantiate-to-bound.md index e54f47d36a5..dafcf2d8a50 100644 --- a/docs/language/informal/instantiate-to-bound.md +++ b/docs/language/informal/instantiate-to-bound.md @@ -4,7 +4,7 @@ **Version**: 0.10 (2018-10-31) -**Status**: Implemented. +**Status**: Background material, normative language now in dartLangSpec.tex. Based on [this description](https://github.com/dart-lang/sdk/issues/27526#issuecomment-260021397) by leafp@.