Implement covariant handling for dartdoc (#1782)

* Covariant implementation

* dartfmt && rebuild test docs

* Fix up test stub that got forgotten

* Update test package docs post merge

Author: jcollins-g

lib/src/model.dart

@@ -68,6 +68,7 @@ const Map<String, int> featureOrder = const {
   'read-only': 1,
   'write-only': 1,
   'read / write': 1,
+  'covariant': 2,
   'final': 2,
   'inherited': 3,
 };
@@ -355,9 +356,17 @@ class Accessor extends ModelElement implements EnclosedElement {
         _accessor.enclosingElement, library, packageGraph);
   }
 
+  @override
+  Set<String> get features {
+    if (!isCovariant) return super.features;
+    return super.features..add('covariant');
+  }
+
   @override
   bool get isCanonical => enclosingCombo.isCanonical;
 
+  bool get isCovariant => isSetter && parameters.first.isCovariant;
+
   bool get isInherited => false;
 
   @override
@@ -1621,6 +1630,12 @@ class Field extends ModelElement
   @override
   bool get isConst => _field.isConst;
 
+  /// Returns true if the FieldElement is covariant, or if the first parameter
+  /// for the setter is covariant.
+  @override
+  bool get isCovariant =>
+      setter?.isCovariant == true || (_field as FieldElementImpl).isCovariant;
+
   @override
   bool get isFinal {
     /// isFinal returns true for the field even if it has an explicit getter
@@ -1722,9 +1737,12 @@ abstract class GetterSetterCombo implements ModelElement {
     if (readOnly && !isFinal && !isConst) allFeatures.add('read-only');
     if (writeOnly) allFeatures.add('write-only');
     if (readWrite) allFeatures.add('read / write');
+    if (isCovariant) allFeatures.add('covariant');
     return allFeatures;
   }
 
+  bool get isCovariant => false;
+
   @override
   ModelElement enclosingElement;
   bool get isInherited;
@@ -3577,6 +3595,9 @@ abstract class ModelElement extends Canonicalization
         buf.write('<span>$annotation</span> ');
       });
     }
+    if (param.isCovariant) {
+      buf.write('<span>covariant</span> ');
+    }
     if (paramModelType is CallableElementTypeMixin) {
       String returnTypeName;
       if (paramModelType.isTypedef) {
@@ -5781,6 +5802,8 @@ class Parameter extends ModelElement implements EnclosedElement {
     return '${enclosingName}-param-${name}';
   }
 
+  bool get isCovariant => _parameter.isCovariant;
+
   bool get isOptional => _parameter.isOptional;
 
   bool get isOptionalNamed => _parameter.isNamed;

test/model_test.dart

@@ -2210,6 +2210,7 @@ String topLevelFunction(int param1, bool param2, Cool coolBeans,
     Field documentedPartialFieldInSubclassOnly;
     Field ExtraSpecialListLength;
     Field aProperty;
+    Field covariantField, covariantSetter;
 
     setUp(() {
       c = exLibrary.classes.firstWhere((c) => c.name == 'Apple');
@@ -2270,6 +2271,22 @@ String topLevelFunction(int param1, bool param2, Cool coolBeans,
           .firstWhere((c) => c.name == 'AClassWithFancyProperties')
           .allInstanceProperties
           .firstWhere((f) => f.name == 'aProperty');
+      covariantField = fakeLibrary.classes
+          .firstWhere((c) => c.name == 'CovariantMemberParams')
+          .allInstanceProperties
+          .firstWhere((f) => f.name == 'covariantField');
+      covariantSetter = fakeLibrary.classes
+          .firstWhere((c) => c.name == 'CovariantMemberParams')
+          .allInstanceProperties
+          .firstWhere((f) => f.name == 'covariantSetter');
+    });
+
+    test('covariant fields are recognized', () {
+      expect(covariantField.isCovariant, isTrue);
+      expect(covariantField.featuresAsString, contains('covariant'));
+      expect(covariantSetter.isCovariant, isTrue);
+      expect(covariantSetter.setter.isCovariant, isTrue);
+      expect(covariantSetter.featuresAsString, contains('covariant'));
     });
 
     test('indentation is not lost inside indented code samples', () {
@@ -2987,16 +3004,21 @@ String topLevelFunction(int param1, bool param2, Cool coolBeans,
   });
 
   group('Parameter', () {
-    Class c, fClass;
+    Class c, fClass, CovariantMemberParams;
     Method isGreaterThan,
         asyncM,
         methodWithGenericParam,
         paramFromExportLib,
-        methodWithTypedefParam;
+        methodWithTypedefParam,
+        applyCovariantParams;
     Parameter intNumber, intCheckOptional;
 
     setUp(() {
       c = exLibrary.classes.firstWhere((c) => c.name == 'Apple');
+      CovariantMemberParams = fakeLibrary.classes
+          .firstWhere((c) => c.name == 'CovariantMemberParams');
+      applyCovariantParams = CovariantMemberParams.allInstanceMethods
+          .firstWhere((m) => m.name == 'applyCovariantParams');
       paramFromExportLib =
           c.instanceMethods.singleWhere((m) => m.name == 'paramFromExportLib');
       isGreaterThan =
@@ -3014,6 +3036,12 @@ String topLevelFunction(int param1, bool param2, Cool coolBeans,
           .singleWhere((m) => m.name == 'methodWithTypedefParam');
     });
 
+    test('covariant parameters render correctly', () {
+      expect(applyCovariantParams.parameters, hasLength(2));
+      expect(applyCovariantParams.linkedParamsLines,
+          contains('<span>covariant</span>'));
+    });
+
     test('has parameters', () {
       expect(isGreaterThan.parameters, hasLength(2));
     });

testing/test_package/lib/fake.dart

@@ -754,6 +754,16 @@ class WithGetterAndSetter {
   void set lengthX(int _length) {}
 }
 
+/// Test that we can properly handle covariant member parameters.
+class CovariantMemberParams {
+  covariant int covariantField;
+
+  set covariantSetter(covariant int x) {}
+
+  void applyCovariantParams(
+      covariant num aNumber, covariant dynamic aDynamic) {}
+}
+
 /// I have a generic and it extends [Foo2]
 class HasGenericWithExtends<T extends Foo2> {}
 

testing/test_package_docs/fake/ABaseClass-class.html

@@ -55,6 +55,7 @@ <h5>fake library</h5>
       <li><a href="fake/ConstantClass-class.html">ConstantClass</a></li>
       <li><a href="fake/ConstructorTester-class.html">ConstructorTester</a></li>
       <li><a href="fake/Cool-class.html">Cool</a></li>
+      <li><a href="fake/CovariantMemberParams-class.html">CovariantMemberParams</a></li>
       <li><a href="fake/DocumentWithATable-class.html">DocumentWithATable</a></li>
       <li><a href="fake/ExtendsFutureVoid-class.html">ExtendsFutureVoid</a></li>
       <li><a href="fake/ExtraSpecialList-class.html">ExtraSpecialList</a></li>

testing/test_package_docs/fake/AClassUsingASuperMixin-class.html

@@ -55,6 +55,7 @@ <h5>fake library</h5>
       <li><a href="fake/ConstantClass-class.html">ConstantClass</a></li>
       <li><a href="fake/ConstructorTester-class.html">ConstructorTester</a></li>
       <li><a href="fake/Cool-class.html">Cool</a></li>
+      <li><a href="fake/CovariantMemberParams-class.html">CovariantMemberParams</a></li>
       <li><a href="fake/DocumentWithATable-class.html">DocumentWithATable</a></li>
       <li><a href="fake/ExtendsFutureVoid-class.html">ExtendsFutureVoid</a></li>
       <li><a href="fake/ExtraSpecialList-class.html">ExtraSpecialList</a></li>

testing/test_package_docs/fake/AClassUsingNewStyleMixin-class.html

@@ -55,6 +55,7 @@ <h5>fake library</h5>
       <li><a href="fake/ConstantClass-class.html">ConstantClass</a></li>
       <li><a href="fake/ConstructorTester-class.html">ConstructorTester</a></li>
       <li><a href="fake/Cool-class.html">Cool</a></li>
+      <li><a href="fake/CovariantMemberParams-class.html">CovariantMemberParams</a></li>
       <li><a href="fake/DocumentWithATable-class.html">DocumentWithATable</a></li>
       <li><a href="fake/ExtendsFutureVoid-class.html">ExtendsFutureVoid</a></li>
       <li><a href="fake/ExtraSpecialList-class.html">ExtraSpecialList</a></li>

testing/test_package_docs/fake/AClassWithFancyProperties-class.html

@@ -55,6 +55,7 @@ <h5>fake library</h5>
       <li><a href="fake/ConstantClass-class.html">ConstantClass</a></li>
       <li><a href="fake/ConstructorTester-class.html">ConstructorTester</a></li>
       <li><a href="fake/Cool-class.html">Cool</a></li>
+      <li><a href="fake/CovariantMemberParams-class.html">CovariantMemberParams</a></li>
       <li><a href="fake/DocumentWithATable-class.html">DocumentWithATable</a></li>
       <li><a href="fake/ExtendsFutureVoid-class.html">ExtendsFutureVoid</a></li>
       <li><a href="fake/ExtraSpecialList-class.html">ExtraSpecialList</a></li>

testing/test_package_docs/fake/AMixinCallingSuper-class.html

@@ -55,6 +55,7 @@ <h5>fake library</h5>
       <li><a href="fake/ConstantClass-class.html">ConstantClass</a></li>
       <li><a href="fake/ConstructorTester-class.html">ConstructorTester</a></li>
       <li><a href="fake/Cool-class.html">Cool</a></li>
+      <li><a href="fake/CovariantMemberParams-class.html">CovariantMemberParams</a></li>
       <li><a href="fake/DocumentWithATable-class.html">DocumentWithATable</a></li>
       <li><a href="fake/ExtendsFutureVoid-class.html">ExtendsFutureVoid</a></li>
       <li><a href="fake/ExtraSpecialList-class.html">ExtraSpecialList</a></li>

testing/test_package_docs/fake/ATypeTakingClass-class.html

@@ -55,6 +55,7 @@ <h5>fake library</h5>
       <li><a href="fake/ConstantClass-class.html">ConstantClass</a></li>
       <li><a href="fake/ConstructorTester-class.html">ConstructorTester</a></li>
       <li><a href="fake/Cool-class.html">Cool</a></li>
+      <li><a href="fake/CovariantMemberParams-class.html">CovariantMemberParams</a></li>
       <li><a href="fake/DocumentWithATable-class.html">DocumentWithATable</a></li>
       <li><a href="fake/ExtendsFutureVoid-class.html">ExtendsFutureVoid</a></li>
       <li><a href="fake/ExtraSpecialList-class.html">ExtraSpecialList</a></li>

testing/test_package_docs/fake/ATypeTakingClassMixedIn-class.html

@@ -55,6 +55,7 @@ <h5>fake library</h5>
       <li><a href="fake/ConstantClass-class.html">ConstantClass</a></li>
       <li><a href="fake/ConstructorTester-class.html">ConstructorTester</a></li>
       <li><a href="fake/Cool-class.html">Cool</a></li>
+      <li><a href="fake/CovariantMemberParams-class.html">CovariantMemberParams</a></li>
       <li><a href="fake/DocumentWithATable-class.html">DocumentWithATable</a></li>
       <li><a href="fake/ExtendsFutureVoid-class.html">ExtendsFutureVoid</a></li>
       <li><a href="fake/ExtraSpecialList-class.html">ExtraSpecialList</a></li>