Integrated covariant parameter feature specs.

Also updated spec on the static and dynamic types of functions literals
and static functions along with the function objects obtained from
closurizations of them.

Introduced a separate notion of what it means to be a correct override
relation (where the old text used subtyping, which won't suffice, for
several reasons).

Introduced the notion of interfaces as a separate kind of entity that
contains method signatures (again, a new kind of entity), thus
clarifying exactly which pieces of information is available during
static analysis of member accesses, e.g., instance method invocations.

Introduced 'combined' interfaces; they are needed for `mixin`
declarations, and we will specify them soon (so it should be OK to
have them now, even though they are unused).

Change-Id: I6347df49b1aa7a81d74e25904ee75c19e8ac6930
Reviewed-on: https://dart-review.googlesource.com/c/81263
Reviewed-by: Leaf Petersen <leafp@google.com>

docs/language/dart.sty

@@ -84,11 +84,20 @@
 \newcommand{\argumentList}[1]{\metavar{{#1}s}}
 \newcommand{\parameterList}[1]{\metavar{{#1}s}}
 
-\newenvironment{Q}[1]{{\bf #1}}{}
-\newenvironment{rationale}[1]{{\it #1}}{}
-\newenvironment{commentary}[1]{{\sf #1}}{}
+% Colors used for for different kinds of text.
+\definecolor{normativeColor}{rgb}{0,0,0}
+\definecolor{commentaryColor}{rgb}{0.6,0.6,0.6}
+\definecolor{rationaleColor}{rgb}{0.6,0.6,0.6}
 
+% Environments for different kinds of text.
+\newenvironment{Q}[1]{{\bf #1}}{}
+\newenvironment{rationale}[1]{{\color{rationaleColor}\it{#1}}}{}
+\newenvironment{commentary}[1]{{\color{commentaryColor}\sf{#1}}}{}
+
+% Auxiliary functions.
 \newcommand{\flatten}[1]{\ensuremath{\mbox{\it flatten}({#1})}}
+\newcommand{\overrides}[1]{\ensuremath{\mbox{\it overrides}({#1})}}
+\newcommand{\inherited}[1]{\ensuremath{\mbox{\it inherited}({#1})}}
 
 % Used as a mini-section marker, indicating visibly that a range of
 % text (usually just a couple of paragraphs) are concerned with one
@@ -100,9 +109,17 @@
   \def\@programcr{\@addfield\strut}%
   \let\\=\@programcr%
   \relax\@vobeyspaces\obeylines%
-  \ttfamily%
+  \ttfamily\color{commentaryColor}%
   \vspace{1em}
-}{\vspace{1em}}
+}{\normalcolor\vspace{1em}}
+
+\newenvironment{normativeDartCode}[1][!ht] {
+  \def\@programcr{\@addfield\strut}%
+  \let\\=\@programcr%
+  \relax\@vobeyspaces\obeylines%
+  \ttfamily\color{normativeColor}%
+  \vspace{1em}
+}{\normalcolor\vspace{1em}}
 
 % Used for comments in a code context.
 \def\comment#1{\textsf{#1}}
@@ -121,6 +138,103 @@
 \newcommand{\NoIndex}[1]{
   \leavevmode\marginpar{\ensuremath{\diamond}}\emph{#1}}
 
+% Used to specify comma separated lists of similar symbols.
+\newcommand{\List}[3]{\ensuremath{{#1}_{#2},\,\ldots,\ {#1}_{#3}}}
+
+% Used to specify comma separated lists of pairs of similar symbols,
+% as needed, e.g., for declarations of formal parameters.
+% Parameters: Name of first part of pair, name of second part,
+% index at start, index at end.
+\newcommand{\PairList}[4]{\ensuremath{%
+  {#1}_{#3}\ {#2}_{#3},\,\ldots,\ {#1}_{#4}\ {#2}_{#4}}}
+
+% Used to specify comma separated lists of triples of similar symbols,
+% as needed, e.g., for declarations of formal parameters with defaults.
+% Parameters: Name of first part of triple, name of second part,
+% name of third part, index at start, index at end.
+\newcommand{\TripleList}[5]{\ensuremath{%
+  {#1}_{#4}\ {#2}_{#4}\ {#3}_{#4},\,\ldots,\ {#1}_{#5}\ {#2}_{#5}\ {#3}_{#5}}}
+
+% Used to abbreviate \EXTENDS{} in function types.
+\newcommand{\FunctionTypeExtends}{\ensuremath{\triangleleft}}
+
+% Used to specify comma separated lists of pairs of symbols
+% separated by \EXTENDS{}, as needed for type parameter declarations.
+% Parameters: Type parameter name, bound name, number of type parameters.
+\newcommand{\TypeParameters}[3]{\ensuremath{%
+  {#1}_1\,\EXTENDS\,{#2}_1,\,\ldots,\ %
+  {#1}_{#3}\,\EXTENDS\,{#2}_{#3}}}
+
+% For consistency, we may as well use this whenever possible.
+\newcommand{\TypeParametersStd}{\TypeParameters{X}{B}{s}}
+
+% Used to specify comma separated lists of pairs of symbols
+% separated by \EXTENDS{}, as needed for type parameter declarations.
+% Parameters: Type parameter name, bound name, number of type parameters.
+\newcommand{\FTTypeParameters}[3]{\ensuremath{%
+  {#1}_1\FunctionTypeExtends{#2}_1,\,\ldots,\ %
+  {#1}_{#3}\FunctionTypeExtends{#2}_{#3}}}
+
+% Used to specify function types: Same syntax as in source.
+% Arguments: Return type, formal parameter declarations.
+\newcommand{\FunctionTypeSimple}[2]{\code{\ensuremath{#1}\ \FUNCTION({#2})}}
+
+% Used to specify function types: Same syntax as in source.
+% Arguments: Return type, spacer, type parameter name, bound name,
+%   number of type parameters, formal parameter declarations.
+\newcommand{\FunctionType}[6]{\leavevmode\par\noindent\code{%
+  \ensuremath{#1}{#2}\FUNCTION<\FTTypeParameters{#3}{#4}{#5}>({#6})}}
+
+% Used to specify function types with positional optionals:
+% Arguments: Return type, spacer, type parameter name, bound name,
+%   number of type parameters, parameter type, number of required parameters,
+%   number of optional parameters.
+\newcommand{\FunctionTypePositional}[8]{%
+  \FunctionType{#1}{#2}{#3}{#4}{#5}{\List{#6}{1}{#7},\ %
+    [\List{#6}{{#7}+1}{{#7}+{#8}}]}}
+
+% Used to specify function types with named parameters:
+% Arguments: Return type, spacer, type parameter name, bound name,
+%   number of type parameters, parameter type, number of required parameters,
+%   name of optional parameters, number of optional parameters.
+\newcommand{\FunctionTypeNamed}[9]{%
+  \FunctionType{#1}{#2}{#3}{#4}{#5}{\List{#6}{1}{#7},\ %
+    \{\PairList{#6}{#8}{{#7}+1}{{#7}+{#9}}\}}}
+
+% Used to specify function types with no optional parameters:
+% Arguments: Return type, spacer, type parameter name, bound name,
+%   number of type parameters, parameter type,
+%   number of parameters (all required).
+\newcommand{\FunctionTypeAllRequired}[7]{%
+  \FunctionType{#1}{#2}{#3}{#4}{#5}{\List{#6}{1}{#7}}}
+
+\newcommand{\FunctionTypePositionalStd}[1]{%
+  \FunctionTypePositional{#1}{ }{X}{B}{s}{T}{n}{k}}
+
+\newcommand{\FunctionTypeNamedStd}[1]{%
+  \FunctionTypeNamed{#1}{ }{X}{B}{s}{T}{n}{x}{k}}
+
+\newcommand{\FunctionTypeAllRequiredStd}[1]{%
+  \FunctionTypeAllRequired{#1}{ }{X}{B}{s}{T}{n}}
+
+\newcommand{\FunctionTypePositionalStdCr}[1]{%
+  \FunctionTypePositional{#1}{\\}{X}{B}{s}{T}{n}{k}}
+
+\newcommand{\FunctionTypeNamedStdCr}[1]{%
+  \FunctionTypeNamed{#1}{\\}{X}{B}{s}{T}{n}{x}{k}}
+
+\newcommand{\FunctionTypeAllRequiredStdCr}[1]{%
+  \FunctionTypeAllRequired{#1}{\\}{X}{B}{s}{T}{n}}
+
+\newcommand{\MoreSignatureSpecificSymbol}{\ensuremath{\preceq}}
+\newcommand{\NotMoreSignatureSpecificSymbol}{\ensuremath{\not\preceq}}
+\newcommand{\LessSignatureSpecificSymbol}{\ensuremath{\succeq}}
+
+\newcommand{\MoreSignatureSpecific}[2]{%
+  \ensuremath{{#1}\MoreSignatureSpecificSymbol{#2}}}
+\newcommand{\NotMoreSignatureSpecific}[2]{%
+  \ensuremath{{#1}\NotMoreSignatureSpecificSymbol{#2}}}
+
 % ----------------------------------------------------------------------
 % Support for hash valued Location Markers
 
@@ -140,7 +254,8 @@
 
 % insert location marker showing hash value of following paragraph
 \newcommand{\LMHash}[1]{\leavevmode\marginpar{\quad%
-    \raisebox{0.5ex}{\miniscule{\color{LMdim}#1}}\vspace{-2\baselineskip}}}
+    \raisebox{0.5ex}{\miniscule{\color{LMdim}#1}}\vspace{-2\baselineskip}}%
+  \color{normativeColor}}
 
 % support convenient renewcommand
 \let\OriginalLMHash\LMHash

docs/language/informal/covariant-from-class.md

@@ -2,7 +2,8 @@
 
 **Owner**: eernst@
 
-**Status**: Implemented.
+**Status**: This document is now background material.
+For normative text, please consult the language specification.
 
 **Version**: 0.6 (2018-06-01)
 

docs/language/informal/covariant-overrides.md

@@ -2,7 +2,8 @@
 
 **Owner**: rnystrom@, eernst@.
 
-**Status**: Implemented.
+**Status**: This document is now background material.
+For normative text, please consult the language specification.
 
 **Version**: 1.1 (Oct 10, 2017).
 

docs/language/informal/interface-conflicts.md

@@ -2,7 +2,11 @@
 
 **Owner**: eernst@
 
-**Status**: Under discussion.
+**Status**: Background material, normative text is now in dartLangSpec.tex.
+Note that the rules have changed, which means that
+**this document cannot be used as a reference**, it can only be
+used to get an overview of the ideas; please refer to the language
+specification for all technical details.
 
 **Version**: 0.3 (2018-04-24)