Don't document elements with @internal (#4048)

Makes members with the `@internal` not part of the public interface.

#2418

Author: sigurdm

lib/src/model/model_element.dart

@@ -427,6 +427,12 @@ abstract class ModelElement
       }
     }
 
+    if (element.nonSynthetic2 case Annotatable(:var metadata2)) {
+      if (metadata2.hasInternal) {
+        return false;
+      }
+    }
+
     return !element.hasPrivateName && !hasNodoc;
   }();
 

test/end2end/model_test.dart

@@ -3801,6 +3801,35 @@ String? topLevelFunction(int param1, bool param2, Cool coolBeans,
           equals('Setter docs should be shown.'));
     });
 
+    test('@internal annotation hides element from docs', () {
+      expect(exLibrary.properties.named('topLevelInternal').isPublic, false);
+
+      expect(
+          exLibrary.classes
+              .named('Apple')
+              .allFields
+              .named('internalField')
+              .isPublic,
+          isFalse);
+
+      expect(
+          exLibrary.classes
+              .named('Apple')
+              .instanceMethods
+              .named('internalMethod')
+              .isPublicAndPackageDocumented,
+          isFalse);
+
+      // The overridden method is not internal, and thus exposed.
+      expect(
+          exLibrary.classes
+              .named('B')
+              .instanceMethods
+              .named('internalMethod')
+              .isPublicAndPackageDocumented,
+          isTrue);
+    });
+
     test('type arguments are correct', () {
       var modelType = mapWithDynamicKeys.modelType as ParameterizedElementType;
       expect(modelType.typeArguments, hasLength(2));

testing/test_package/lib/example.dart

@@ -13,7 +13,7 @@ import 'package:test_package_imported/main.dart';
 
 export 'package:args/args.dart' show ArgParser;
 export 'dart:core' show deprecated, Deprecated;
-import 'package:meta/meta.dart' show protected, factory;
+import 'package:meta/meta.dart' show protected, factory, internal;
 
 export 'fake.dart' show Cool, ClassTemplateOneLiner;
 export 'src/mylib.dart' show Helper;
@@ -30,6 +30,11 @@ const String COMPLEX_COLOR = 'red' + '-' + 'green' + '-' + 'blue';
 /// @nodoc
 const DO_NOT_DOCUMENT = 'not documented';
 
+/// top level internal variable
+// ignore: invalid_internal_annotation
+@internal
+final topLevelInternal = 'not documented';
+
 /// This is the same name as a top-level const from the fake lib.
 const incorrectDocReference = 'same name as const from fake';
 
@@ -122,6 +127,10 @@ class Apple {
 
   /// @nodoc no docs
   int? notDocumented;
+  
+  /// No public docs for this
+  @internal
+  int? internalField;
 
   ///Constructor
   Apple();
@@ -164,6 +173,11 @@ class Apple {
    * @nodoc method not documented
    */
   void notAPublicMethod() {}
+  
+  /// No public docs for this  
+  // ignore: invalid_internal_annotation 
+  @internal
+  void internalMethod() {}
 
   void paramFromExportLib(Helper helper) {}
 
@@ -236,6 +250,8 @@ class B extends Apple with Cat {
 
   @override
   void abstractMethod() {}
+  
+  @override void internalMethod() {}
 }
 
 /// Reference to nullable type: [Apple?] and null-checked variable [myNumber!].