commit 6391c68e2f183fab1675edc82ff3b96891b4c5db
author Sigurd Meldgaard <sigurdm@google.com> Fri May 23 12:58:46 2025 +0200
committer GitHub <noreply@github.com> Fri May 23 12:58:46 2025 +0200
tree 17bb73ea919a2f0306eb6a4371d959be9a4df0d0
parent 2e124adba3034032f66fc444e8b632f0ebe31ced

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

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

#2418

lib/src/model/model_element.dart

diff --git a/lib/src/model/model_element.dart b/lib/src/model/model_element.dart
index 8dcbbc9..6ccae3d 100644
--- a/lib/src/model/model_element.dart
+++ b/lib/src/model/model_element.dart
@@ -427,6 +427,12 @@
       }
     }
 
+    if (element.nonSynthetic2 case Annotatable(:var metadata2)) {
+      if (metadata2.hasInternal) {
+        return false;
+      }
+    }
+
     return !element.hasPrivateName && !hasNodoc;
   }();
 

test/end2end/model_test.dart

diff --git a/test/end2end/model_test.dart b/test/end2end/model_test.dart
index 0d1170d..319b2af 100644
--- a/test/end2end/model_test.dart
+++ b/test/end2end/model_test.dart
@@ -3801,6 +3801,35 @@
           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

diff --git a/testing/test_package/lib/example.dart b/testing/test_package/lib/example.dart
index eda3269..8506528 100644
--- a/testing/test_package/lib/example.dart
+++ b/testing/test_package/lib/example.dart
@@ -13,7 +13,7 @@
 
 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 @@
 /// @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 @@
 
   /// @nodoc no docs
   int? notDocumented;
+  
+  /// No public docs for this
+  @internal
+  int? internalField;
 
   ///Constructor
   Apple();
@@ -164,6 +173,11 @@
    * @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 @@
 
   @override
   void abstractMethod() {}
+  
+  @override void internalMethod() {}
 }
 
 /// Reference to nullable type: [Apple?] and null-checked variable [myNumber!].