Deprecate the use of 'kind' in pub-data.json. (#1292)

* Deprecate the use of 'kind' in pub-data.json.

* Remove fixed dartdoc version from end2end tests.

* Updated end2end tests.

CHANGELOG.md

@@ -1,6 +1,9 @@
 ## 0.21.44
 
 - Fix: `dart:ui_web` is now part of the SDK-detection library list.
+- The use of `kind` in `pub-data.json` is deprecated, as it may contain
+  different value on different `dartdoc` version. The field may be
+  removed in a future version.
 
 ## 0.21.43
 

lib/src/dartdoc/dartdoc_index.dart

@@ -9,6 +9,7 @@ import 'package:json_annotation/json_annotation.dart';
 part 'dartdoc_index.g.dart';
 
 // TODO(https://github.com/dart-lang/pana/issues/1273): remove these and use a different pub-data.json file format.
+@Deprecated('Do not use, will be removed.')
 const kindNames = <int, String>{
   0: 'accessor',
   1: 'constant',

lib/src/dartdoc/index_to_pubdata.dart

@@ -24,7 +24,7 @@ PubDartdocData dataFromDartdocIndex(DartdocIndex index) {
   }
   final apiElements = <ApiElement>[];
   for (final e in entries) {
-    final kind = kindNames[e.kind!]!;
+    final kind = e.kind == null ? null : kindNames[e.kind!];
     final showHref = e.isLibrary || e.isClass;
     final parent = hrefToQualifiedNames[e.enclosedBy?.href ?? ''];
     apiElements.add(ApiElement(
@@ -48,7 +48,7 @@ PubDartdocData dataFromDartdocIndex(DartdocIndex index) {
     // Too much content, removing the documentation from everything except
     // libraries and classes.
     apiElements
-        .where((e) => e.kind != 'library' && e.kind != 'class')
+        .where((e) => !e.isLibrary && !e.isClass)
         .forEach((e) => e.documentation = null);
   }
 

lib/src/dartdoc/pub_dartdoc_data.dart

@@ -26,7 +26,8 @@ class PubDartdocData {
 class ApiElement {
   /// The last part of the [qualifiedName].
   final String name;
-  final String kind;
+  @Deprecated('Do not use, will be removed.')
+  final String? kind;
   final String? parent;
   final String? source;
   final String? href;
@@ -53,6 +54,10 @@ class ApiElement {
   Map<String, dynamic> toJson() => _$ApiElementToJson(this);
 
   String get qualifiedName => parent == null ? name : '$parent.$name';
+
+  /// Wether the entry is a top-level library.
+  late final isLibrary = href != null && href!.endsWith('-library.html');
+  late final isClass = href != null && href!.endsWith('-class.html');
 }
 
 /// The documentation coverage numbers and the derived scores.

test/end2end_test.dart

@@ -41,7 +41,6 @@ void main() {
       pubCacheDir: pubCacheDir,
       panaCacheDir: panaCacheDir,
       pubHostedUrl: 'http://127.0.0.1:${httpServer.port}',
-      globalDartdocVersion: '7.0.0',
     );
   });
 

test/goldens/end2end/url_launcher-6.1.12.json

@@ -125,7 +125,7 @@
         "grantedPoints": 20,
         "maxPoints": 20,
         "status": "passed",
-        "summary": "### [*] 10/10 points: 20% or more of the public API has dartdoc comments\n\n29 out of 33 API elements (87.9 %) have documentation comments.\n\nSome symbols that are missing documentation: `link`, `url_launcher`, `url_launcher_string`, `LaunchMode`.\n\n### [*] 10/10 points: Package has an example\n"
+        "summary": "### [*] 10/10 points: 20% or more of the public API has dartdoc comments\n\n29 out of 33 API elements (87.9 %) have documentation comments.\n\nSome symbols that are missing documentation: `link`, `url_launcher`, `LaunchMode`, `url_launcher_string`.\n\n### [*] 10/10 points: Package has an example\n"
       },
       {
         "id": "platform",

test/goldens/end2end/url_launcher-6.1.12.json_report.md

@@ -19,7 +19,7 @@ Detected license: `BSD-3-Clause`.
 
 29 out of 33 API elements (87.9 %) have documentation comments.
 
-Some symbols that are missing documentation: `link`, `url_launcher`, `url_launcher_string`, `LaunchMode`.
+Some symbols that are missing documentation: `link`, `url_launcher`, `LaunchMode`, `url_launcher_string`.
 
 ### [*] 10/10 points: Package has an example