Remove dartdoc section generation + joining from public API. (#1318)

dart-lang · Jan 17, 2024 · 5a7f35a · 5a7f35a
1 parent 6670b00
commit 5a7f35a
Show file tree

Hide file tree

Showing 8 changed files with 7 additions and 218 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,7 @@
   - deprecated APIs
   - `InspectOptions.checkRemoteRepository` - repositories are verified by default
   - `ProcessOutput.asBytes`
+  - `Report.joinSection()`
   - `ToolEnvironment`:
     - removed parameters from `dartdoc()`
     - `detectFlutterUse()`
@@ -16,6 +17,8 @@
   - `changelogFileNames`
   - `currentAnalysisOptionsFileName`
   - `dartdocFailedSection`
+  - `documentationCoverageSection()`
+  - `documentationSectionTitle`
   - `firstFileFromNames`
   - `licenseFileNames`
   - `pubspecParseError`

diff --git a/lib/pana.dart b/lib/pana.dart
@@ -2,7 +2,6 @@
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
-export 'src/dartdoc_analyzer.dart';
 export 'src/download_utils.dart';
 export 'src/maintenance.dart' show exampleFileCandidates;
 export 'src/model.dart';

diff --git a/lib/src/dartdoc/dartdoc.dart b/lib/src/dartdoc/dartdoc.dart
@@ -13,7 +13,7 @@ import 'dartdoc_index.dart';
 import 'index_to_pubdata.dart';
 import 'pub_dartdoc_data.dart';
 
-final dartdocSubsectionHeadline =
+final _dartdocSubsectionHeadline =
     '20% or more of the public API has dartdoc comments';
 
 Future<PubDartdocData> generateAndSavePubDataJson(
@@ -29,7 +29,7 @@ Future<PubDartdocData> generateAndSavePubDataJson(
 
 Subsection dartdocFailedSubsection(String reason) {
   return Subsection(
-    dartdocSubsectionHeadline,
+    _dartdocSubsectionHeadline,
     [RawParagraph(reason)],
     0,
     10,
@@ -68,7 +68,7 @@ Future<Subsection> createDocumentationCoverageSection(
   }
 
   return Subsection(
-    dartdocSubsectionHeadline,
+    _dartdocSubsectionHeadline,
     [RawParagraph(summary.toString())],
     grantedPoints,
     maxPoints,

diff --git a/lib/src/dartdoc_analyzer.dart b/lib/src/dartdoc_analyzer.dart
diff --git a/lib/src/model.dart b/lib/src/model.dart
@@ -4,7 +4,6 @@
 
 import 'dart:math';
 
-import 'package:collection/collection.dart';
 import 'package:json_annotation/json_annotation.dart';
 import 'package:pub_semver/pub_semver.dart';
 
@@ -237,41 +236,6 @@ class Report {
 
   int get maxPoints =>
       sections.fold<int>(0, (sum, section) => sum + section.maxPoints);
-
-  /// Creates a new [Report] instance with [section] extending and already
-  /// existing [ReportSection]. The sections are matched via the `title`.
-  ///
-  /// The granted and max points will be added to the existing section.
-  /// The status will be min of the two statuses.
-  ///
-  /// The summary will be appended to the end of the existing summary.
-  ///
-  ///
-  /// If there is no section matched, the section will be added to the end of
-  /// the sections list.
-  Report joinSection(ReportSection section) {
-    final matched = sections.firstWhereOrNull(
-        (s) => (s.id == section.id) || s.title == section.title);
-    if (matched == null) {
-      return Report(sections: [...sections, section]);
-    } else {
-      return Report(
-          sections: sections.map(
-        (s) {
-          if (s != matched) {
-            return s;
-          }
-          return ReportSection(
-              id: s.id,
-              title: s.title,
-              maxPoints: s.maxPoints + section.maxPoints,
-              grantedPoints: s.grantedPoints + section.grantedPoints,
-              summary: [s.summary.trim(), section.summary.trim()].join('\n\n'),
-              status: minStatus(s.status, section.status)!);
-        },
-      ).toList());
-    }
-  }
 }
 
 abstract class ReportSectionId {

diff --git a/lib/src/report/documentation.dart b/lib/src/report/documentation.dart
@@ -8,7 +8,6 @@ import 'package:collection/collection.dart';
 import 'package:path/path.dart' as p;
 
 import '../dartdoc/dartdoc.dart';
-import '../dartdoc_analyzer.dart';
 import '../maintenance.dart';
 import '../model.dart';
 import '../package_context.dart';
@@ -70,7 +69,7 @@ Future<ReportSection> hasDocumentation(PackageContext context) async {
   final example = await _exampleSubsection(context);
   return makeSection(
     id: ReportSectionId.documentation,
-    title: documentationSectionTitle,
+    title: 'Provide documentation',
     maxPoints: (documentation?.maxPoints ?? 0) + example.maxPoints,
     subsections: [
       if (documentation != null) documentation,

diff --git a/test/model_test.dart b/test/model_test.dart
@@ -6,105 +6,6 @@ import 'package:pana/src/model.dart';
 import 'package:test/test.dart';
 
 void main() {
-  group('Report', () {
-    test('join section with no match', () {
-      final report = Report(sections: [
-        ReportSection(
-          id: 'a',
-          title: 'a',
-          grantedPoints: 5,
-          maxPoints: 5,
-          summary: 'something',
-          status: ReportStatus.partial,
-        ),
-      ]);
-
-      final nr = report.joinSection(ReportSection(
-        id: 'b',
-        title: 'b',
-        grantedPoints: 10,
-        maxPoints: 10,
-        summary: 'other',
-        status: ReportStatus.passed,
-      ));
-
-      expect(nr.toJson(), {
-        'sections': [
-          {
-            'id': 'a',
-            'title': 'a',
-            'grantedPoints': 5,
-            'maxPoints': 5,
-            'summary': 'something',
-            'status': 'partial'
-          },
-          {
-            'id': 'b',
-            'title': 'b',
-            'grantedPoints': 10,
-            'maxPoints': 10,
-            'summary': 'other',
-            'status': 'passed',
-          },
-        ]
-      });
-    });
-
-    test('join with match', () {
-      final report = Report(sections: [
-        ReportSection(
-          id: 'a',
-          title: 'a',
-          grantedPoints: 5,
-          maxPoints: 5,
-          summary: 'something\n',
-          status: ReportStatus.partial,
-        ),
-        ReportSection(
-          id: 'b',
-          title: 'b',
-          grantedPoints: 6,
-          maxPoints: 10,
-          summary: 'other',
-          status: ReportStatus.passed,
-        ),
-      ]);
-
-      final nr = report.joinSection(ReportSection(
-        id: 'a',
-        title: 'a',
-        grantedPoints: 3,
-        maxPoints: 7,
-        summary: '\nanother thing\n',
-        status: ReportStatus.failed,
-      ));
-
-      expect(
-        nr.toJson(),
-        {
-          'sections': [
-            {
-              'id': 'a',
-              'title': 'a',
-              'grantedPoints': 8,
-              'maxPoints': 12,
-              'summary': 'something\n\nanother thing',
-              'status': 'failed'
-            },
-            {
-              'id': 'b',
-              'title': 'b',
-              'grantedPoints': 6,
-              'maxPoints': 10,
-              'summary': 'other',
-              'status': 'passed',
-            },
-          ]
-        },
-      );
-    });
-  });
-
   group('PanaRuntimeInfo', () {
     test('no Flutter SDK', () {
       final info = PanaRuntimeInfo(panaVersion: '1.0.0', sdkVersion: '2.0.0');

diff --git a/test/report/documentation_test.dart b/test/report/documentation_test.dart
@@ -12,28 +12,6 @@ import '../package_descriptor.dart';
 
 void main() {
   group('Provide documentation', () {
-    test('documentation percent', () {
-      expect(documentationCoverageSection(documented: 1, total: 21).summary,
-          contains('(4.8 %)'));
-      expect(documentationCoverageSection(documented: 0, total: 0).summary,
-          contains('(100.0 %)'));
-      expect(documentationCoverageSection(documented: 5, total: 7).summary,
-          contains('(71.4 %)'));
-      expect(documentationCoverageSection(documented: 7, total: 7).summary,
-          contains('(100.0 %)'));
-    });
-
-    test('documentation title', () {
-      expect(documentationCoverageSection(documented: 1, total: 21).summary,
-          contains('### [x] 0/10 points'));
-      expect(documentationCoverageSection(documented: 0, total: 0).summary,
-          contains('### [*] 10/10 points'));
-      expect(documentationCoverageSection(documented: 5, total: 7).summary,
-          contains('### [*] 10/10 points'));
-      expect(documentationCoverageSection(documented: 7, total: 7).summary,
-          contains('### [*] 10/10 points'));
-    });
-
     test('finds example', () async {
       final descriptor = package('my_package', extraFiles: [
         d.dir('example', [