Correct FunctionType docs
In particular, revert text about the parameters being sorted.
Also, put all text in present tense.
Also, follow some Effective Dart:
* https://dart.dev/effective-dart/documentation#do-start-doc-comments-with-a-single-sentence-summary
* https://dart.dev/effective-dart/documentation#do-separate-the-first-sentence-of-a-doc-comment-into-its-own-paragraph
* https://dart.dev/effective-dart/documentation#prefer-starting-function-or-method-comments-with-third-person-verbs
* https://dart.dev/effective-dart/documentation#prefer-starting-a-non-boolean-variable-or-property-comment-with-a-noun-phrase
Fixes https://github.com/dart-lang/sdk/issues/52780
Change-Id: Idbe1a1a80281071db5fe25c1faa8ccd5be1a5322
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/337606
Commit-Queue: Samuel Rawlins <srawlins@google.com>
Reviewed-by: Brian Wilkerson <brianwilkerson@google.com>
diff --git a/pkg/analyzer/lib/dart/element/type.dart b/pkg/analyzer/lib/dart/element/type.dart
index 310cb11..cc6688a 100644
--- a/pkg/analyzer/lib/dart/element/type.dart
+++ b/pkg/analyzer/lib/dart/element/type.dart
@@ -226,44 +226,49 @@
@override
Null get element2;
- /// Return a map from the names of named parameters to the types of the named
- /// parameters of this type of function. The entries in the map will be
- /// iterated in the same order as the order in which the named parameters were
- /// defined. If there were no named parameters declared then the map will be
- /// empty.
+ /// A map from the names of named parameters to the types of the named
+ /// parameters of this type of function.
+ ///
+ /// The entries in the map are not necessarily iterated in the same order as
+ /// the order in which the named parameters are defined. If there are no
+ /// named parameters declared, then the map will be empty.
Map<String, DartType> get namedParameterTypes;
/// The names of the required positional parameters of this type of function,
- /// in the order that the parameters appear.
+ /// not necessarily in the order that the parameters appear.
List<String> get normalParameterNames;
- /// Return a list containing the types of the normal parameters of this type
- /// of function. The parameter types are in the same order as they appear in
- /// the declaration of the function.
+ /// A list containing the types of the normal parameters of this type of
+ /// function.
+ ///
+ /// The parameter types are not necessarily in the same order as they appear
+ /// in the declaration of the function.
List<DartType> get normalParameterTypes;
/// The names of the optional positional parameters of this type of function,
- /// in the order that the parameters appear.
+ /// not necessarily in the order that the parameters appear.
List<String> get optionalParameterNames;
- /// Return a map from the names of optional (positional) parameters to the
- /// types of the optional parameters of this type of function. The entries in
- /// the map will be iterated in the same order as the order in which the
- /// optional parameters were defined. If there were no optional parameters
- /// declared then the map will be empty.
+ /// A map from the names of optional (positional) parameters to the types of
+ /// the optional parameters of this type of function.
+ ///
+ /// The entries in the map are not necessarily iterated in the same order as
+ /// the order in which the optional parameters are defined. If there area no
+ /// optional parameters declared, then the map is empty.
List<DartType> get optionalParameterTypes;
- /// Return a list containing the parameters elements of this type of function.
- /// The parameter types are in the same order as they appear in the
- /// declaration of the function.
+ /// A list containing the parameters elements of this type of function.
+ ///
+ /// The parameter types are not necessarily in the same order as they appear
+ /// in the declaration of the function.
List<ParameterElement> get parameters;
- /// Return the type of object returned by this type of function.
+ /// The type of object returned by this type of function.
DartType get returnType;
- /// The formal type parameters of this generic function.
- /// For example `<T> T -> T`.
- ///
+ /// The formal type parameters of this generic function; for example,
+ /// `<T> T -> T`.
+ //
// TODO(scheglov): Remove the mention for "typeParameters".
// These are distinct from the `typeParameters` list, which contains type
// parameters from surrounding contexts, and thus are free type variables
@@ -271,8 +276,9 @@
List<TypeParameterElement> get typeFormals;
/// Produces a new function type by substituting type parameters of this
- /// function type with the given [argumentTypes]. The resulting function
- /// type will have no type parameters.
+ /// function type with the given [argumentTypes].
+ ///
+ /// The resulting function type has no type parameters.
FunctionType instantiate(List<DartType> argumentTypes);
}
