diff --git a/CHANGELOG.md b/CHANGELOG.md index 446109dad..b94330db4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,7 @@ - Fix: limit number of documentation entries exported in `pub-data.json`. - Fix: Add `dart:js_interop_unsafe` as a web library. +- Pre-compute missing documentation symbol before pruning the results. ## 0.21.42 diff --git a/lib/src/dartdoc/dartdoc.dart b/lib/src/dartdoc/dartdoc.dart index 3d06bdd08..532f0489f 100644 --- a/lib/src/dartdoc/dartdoc.dart +++ b/lib/src/dartdoc/dartdoc.dart @@ -41,10 +41,8 @@ Future createDocumentationCoverageSection( PubDartdocData data) async { final documented = data.coverage?.documented ?? 0; final total = data.coverage?.total ?? 0; - final symbolsMissingDocumentation = data.apiElements - ?.where((e) => e.documentation == null || e.documentation!.isEmpty) - .map((e) => e.name) - .toList(); + final symbolsMissingDocumentation = + data.coverage?.symbolsMissingDocumentation; final maxPoints = 10; final ratio = total <= 0 ? 1.0 : documented / total; diff --git a/lib/src/dartdoc/index_to_pubdata.dart b/lib/src/dartdoc/index_to_pubdata.dart index 694a819af..73c6cf147 100644 --- a/lib/src/dartdoc/index_to_pubdata.dart +++ b/lib/src/dartdoc/index_to_pubdata.dart @@ -38,6 +38,12 @@ PubDartdocData dataFromDartdocIndex(DartdocIndex index) { } final documented = apiElements.where((e) => e.documentation != null).length; + final symbolsMissingDocumentation = apiElements + .where((e) => e.documentation == null) + .map((e) => e.name) + .take(5) + .toList(); + if (documented > 1000) { // Too much content, removing the documentation from everything except // libraries and classes. @@ -50,6 +56,7 @@ PubDartdocData dataFromDartdocIndex(DartdocIndex index) { coverage: Coverage( documented: documented, total: apiElements.length, + symbolsMissingDocumentation: symbolsMissingDocumentation, ), apiElements: apiElements, ); diff --git a/lib/src/dartdoc/pub_dartdoc_data.dart b/lib/src/dartdoc/pub_dartdoc_data.dart index b9c86c0bd..3f1122fba 100644 --- a/lib/src/dartdoc/pub_dartdoc_data.dart +++ b/lib/src/dartdoc/pub_dartdoc_data.dart @@ -64,9 +64,15 @@ class Coverage { /// The number of API elements with accepted documentation. final int documented; + /// Some of the API symbols that are without accepted documentation. + /// + /// To limit the output size, we only store a subset of the missing symbols. + final List? symbolsMissingDocumentation; + Coverage({ required this.total, required this.documented, + required this.symbolsMissingDocumentation, }); factory Coverage.fromJson(Map json) => diff --git a/lib/src/dartdoc/pub_dartdoc_data.g.dart b/lib/src/dartdoc/pub_dartdoc_data.g.dart index f3381a6d6..8df20a56e 100644 --- a/lib/src/dartdoc/pub_dartdoc_data.g.dart +++ b/lib/src/dartdoc/pub_dartdoc_data.g.dart @@ -64,9 +64,25 @@ Map _$ApiElementToJson(ApiElement instance) { Coverage _$CoverageFromJson(Map json) => Coverage( total: json['total'] as int, documented: json['documented'] as int, + symbolsMissingDocumentation: + (json['symbolsMissingDocumentation'] as List?) + ?.map((e) => e as String) + .toList(), ); -Map _$CoverageToJson(Coverage instance) => { - 'total': instance.total, - 'documented': instance.documented, - }; +Map _$CoverageToJson(Coverage instance) { + final val = { + 'total': instance.total, + 'documented': instance.documented, + }; + + void writeNotNull(String key, dynamic value) { + if (value != null) { + val[key] = value; + } + } + + writeNotNull( + 'symbolsMissingDocumentation', instance.symbolsMissingDocumentation); + return val; +}