Use pana-integrated dartdoc instead of pkg/pub_dartdoc. (dart-lang#7175)

isoos · Nov 15, 2023 · 1d8d861 · 1d8d861
1 parent 3317dd2
commit 1d8d861
Show file tree

Hide file tree

Showing 24 changed files with 114 additions and 316 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,9 @@ Important changes to data models, configuration, and migrations between each
 AppEngine version, listed here to ease deployment and troubleshooting.
 
 ## Next Release (replace with git tag when deployed)
+ * Bumped runtimeVersion to `2023.11.15`.
+ * Upgraded pana to `0.21.42`.
+ * Note: Started running `dartdoc` from `pana`.
 
 ## `20231115t090700-all`
  * Hiding invalid popularity scores.

diff --git a/app/lib/shared/versions.dart b/app/lib/shared/versions.dart
@@ -24,10 +24,10 @@ final RegExp runtimeVersionPattern = RegExp(r'^\d{4}\.\d{2}\.\d{2}$');
 /// when the version switch happens.
 const _acceptedRuntimeVersions = <String>[
   // The current [runtimeVersion].
-  '2023.11.02',
+  '2023.11.15',
   // Fallback runtime versions.
+  '2023.11.02',
   '2023.10.18',
-  '2023.10.10',
 ];
 
 /// Sets the current runtime versions.

diff --git a/app/pubspec.lock b/app/pubspec.lock
@@ -544,10 +544,10 @@ packages:
     dependency: "direct main"
     description:
       name: pana
-      sha256: "0a2546792c71440b69e4dd73d9cd310dab6404c18ce6c0e8ceeb1453249c5d27"
+      sha256: d8c24d31fbf66b9c8c6c5e31c39b094c8535ed5bd152dbce9642049e6e76965d
       url: "https://pub.dev"
     source: hosted
-    version: "0.21.40"
+    version: "0.21.42"
   path:
     dependency: "direct main"
     description:

diff --git a/app/pubspec.yaml b/app/pubspec.yaml
@@ -53,7 +53,7 @@ dependencies:
   watcher: ^1.0.0
   yaml: '^3.0.0'
   # pana version to be pinned
-  pana: '0.21.40'
+  pana: '0.21.42'
   # 3rd-party packages with pinned versions
   mailer: '6.0.1'
   ulid: '2.0.0'

diff --git a/app/test/shared/versions_test.dart b/app/test/shared/versions_test.dart
@@ -141,6 +141,13 @@ and do not format to also bump the runtimeVersion.''',
     expect(dependency.version.toString(), dartdocVersion);
   });
 
+  test('dartdoc version should match pkg/pub_worker', () async {
+    final content =
+        await File('../pkg/pub_worker/lib/src/bin/pana_wrapper.dart')
+            .readAsString();
+    expect(content, contains("globalDartdocVersion: '$dartdocVersion'"));
+  });
+
   scopedTest('GC is not deleting currently accepted versions', () {
     for (final version in acceptedRuntimeVersions) {
       expect(shouldGCVersion(version), isFalse);

diff --git a/app/test/task/testdata/goldens/packages/oxygen.html b/app/test/task/testdata/goldens/packages/oxygen.html
@@ -234,7 +234,7 @@ <h1 class="hash-header" id="oxygen">
               </div>
               <div class="packages-score packages-score-health">
                 <div class="packages-score-value -has-value">
-                  <span class="packages-score-value-number">110</span>
+                  <span class="packages-score-value-number">120</span>
                   <span class="packages-score-value-sign"></span>
                 </div>
                 <div class="packages-score-label">pub points</div>
@@ -320,7 +320,7 @@ <h3 class="detail-metadata-title">
             </div>
             <div class="packages-score packages-score-health">
               <div class="packages-score-value -has-value">
-                <span class="packages-score-value-number">110</span>
+                <span class="packages-score-value-number">120</span>
                 <span class="packages-score-value-sign"></span>
               </div>
               <div class="packages-score-label">pub points</div>

diff --git a/app/test/task/testdata/goldens/packages/oxygen/changelog.html b/app/test/task/testdata/goldens/packages/oxygen/changelog.html
@@ -240,7 +240,7 @@ <h2 class="changelog-version hash-header" id="200">
               </div>
               <div class="packages-score packages-score-health">
                 <div class="packages-score-value -has-value">
-                  <span class="packages-score-value-number">110</span>
+                  <span class="packages-score-value-number">120</span>
                   <span class="packages-score-value-sign"></span>
                 </div>
                 <div class="packages-score-label">pub points</div>
@@ -326,7 +326,7 @@ <h3 class="detail-metadata-title">
             </div>
             <div class="packages-score packages-score-health">
               <div class="packages-score-value -has-value">
-                <span class="packages-score-value-number">110</span>
+                <span class="packages-score-value-number">120</span>
                 <span class="packages-score-value-sign"></span>
               </div>
               <div class="packages-score-label">pub points</div>

diff --git a/app/test/task/testdata/goldens/packages/oxygen/example.html b/app/test/task/testdata/goldens/packages/oxygen/example.html
@@ -235,7 +235,7 @@ <h3 class="detail-lead-title">Metadata</h3>
               </div>
               <div class="packages-score packages-score-health">
                 <div class="packages-score-value -has-value">
-                  <span class="packages-score-value-number">110</span>
+                  <span class="packages-score-value-number">120</span>
                   <span class="packages-score-value-sign"></span>
                 </div>
                 <div class="packages-score-label">pub points</div>
@@ -321,7 +321,7 @@ <h3 class="detail-metadata-title">
             </div>
             <div class="packages-score packages-score-health">
               <div class="packages-score-value -has-value">
-                <span class="packages-score-value-number">110</span>
+                <span class="packages-score-value-number">120</span>
                 <span class="packages-score-value-sign"></span>
               </div>
               <div class="packages-score-label">pub points</div>

diff --git a/app/test/task/testdata/goldens/packages/oxygen/install.html b/app/test/task/testdata/goldens/packages/oxygen/install.html
@@ -263,7 +263,7 @@ <h3>Import it</h3>
               </div>
               <div class="packages-score packages-score-health">
                 <div class="packages-score-value -has-value">
-                  <span class="packages-score-value-number">110</span>
+                  <span class="packages-score-value-number">120</span>
                   <span class="packages-score-value-sign"></span>
                 </div>
                 <div class="packages-score-label">pub points</div>
@@ -349,7 +349,7 @@ <h3 class="detail-metadata-title">
             </div>
             <div class="packages-score packages-score-health">
               <div class="packages-score-value -has-value">
-                <span class="packages-score-value-number">110</span>
+                <span class="packages-score-value-number">120</span>
                 <span class="packages-score-value-sign"></span>
               </div>
               <div class="packages-score-label">pub points</div>

diff --git a/app/test/task/testdata/goldens/packages/oxygen/license.html b/app/test/task/testdata/goldens/packages/oxygen/license.html
@@ -236,7 +236,7 @@ <h2>License</h2>
               </div>
               <div class="packages-score packages-score-health">
                 <div class="packages-score-value -has-value">
-                  <span class="packages-score-value-number">110</span>
+                  <span class="packages-score-value-number">120</span>
                   <span class="packages-score-value-sign"></span>
                 </div>
                 <div class="packages-score-label">pub points</div>
@@ -322,7 +322,7 @@ <h3 class="detail-metadata-title">
             </div>
             <div class="packages-score packages-score-health">
               <div class="packages-score-value -has-value">
-                <span class="packages-score-value-number">110</span>
+                <span class="packages-score-value-number">120</span>
                 <span class="packages-score-value-sign"></span>
               </div>
               <div class="packages-score-label">pub points</div>

diff --git a/app/test/task/testdata/goldens/packages/oxygen/score.html b/app/test/task/testdata/goldens/packages/oxygen/score.html
@@ -212,7 +212,7 @@ <h3 class="detail-lead-title">Metadata</h3>
                     </div>
                     <div class="score-key-figure">
                       <div class="score-key-figure-title">
-                        <span class="score-key-figure-value">110</span>
+                        <span class="score-key-figure-value">120</span>
                         <span class="score-key-figure-supplemental">/ 140</span>
                       </div>
                       <div class="score-key-figure-label">pub points</div>
@@ -228,7 +228,7 @@ <h3 class="detail-lead-title">Metadata</h3>
                   <p class="analysis-info">
                     We analyzed this package
                     <a class="-x-ago" href="" title="on %%short-dateformat%%" aria-label="Switch between date and elapsed time." aria-role="button" data-timestamp="%%time-ago-millis%%">%%time-ago%%</a>
-                    , and awarded it 110 pub points (of a possible 140):
+                    , and awarded it 120 pub points (of a possible 140):
                   </p>
                   <div class="pkg-report">
                     <div class="pkg-report-section foldable">
@@ -362,11 +362,11 @@ <h3>
                     <div class="pkg-report-section foldable">
                       <div class="pkg-report-header foldable-button" data-ga-click-event="toggle-report-section-documentation">
                         <div class="pkg-report-header-icon">
-                          <img class="pkg-report-icon" src="/static/hash-%%etag%%/img/report-missing-icon-red.svg" alt="icon indicating section status" width="18" height="18"/>
+                          <img class="pkg-report-icon" src="/static/hash-%%etag%%/img/report-ok-icon-green.svg" alt="icon indicating section status" width="18" height="18"/>
                         </div>
                         <div class="pkg-report-header-title">Provide documentation</div>
-                        <div class="pkg-report-header-score -is-red">
-                          <span class="pkg-report-header-score-granted">10</span>
+                        <div class="pkg-report-header-score">
+                          <span class="pkg-report-header-score-granted">20</span>
                           /
                           <span class="pkg-report-header-score-max">20</span>
                           <img class="foldable-icon" src="/static/hash-%%etag%%/img/report-foldable-icon.svg" alt="icon to trigger folding of the section" width="13" height="6"/>
@@ -377,16 +377,26 @@ <h3>
                           <div class="pkg-report-content-summary markdown-body">
                             <h3>
                               <img class="report-summary-icon" src="/static/hash-%%etag%%/img/report-ok-icon-green.svg"/>
-                              10/10 points: Package has an example and has no issues with screenshots
+                              10/10 points: 20% or more of the public API has dartdoc comments
                             </h3>
+                            <p>2 out of 9 API elements (22.2 %) have documentation comments.</p>
+                            <p>
+                              Some symbols that are missing documentation:
+                              <code>oxygen</code>
+                              ,
+                              <code>MainClass</code>
+                              ,
+                              <code>MainClass</code>
+                              ,
+                              <code>text</code>
+                              ,
+                              <code>TypeEnum</code>
+                              .
+                            </p>
                             <h3>
-                              <img class="report-summary-icon" src="/static/hash-%%etag%%/img/report-missing-icon-red.svg"/>
-                              0/10 points: 20% or more of the public API has dartdoc comments
+                              <img class="report-summary-icon" src="/static/hash-%%etag%%/img/report-ok-icon-green.svg"/>
+                              10/10 points: Package has an example and has no issues with screenshots
                             </h3>
-                            <ul>
-                              <li>1 out of 11 API elements (9.1 %) have documentation comments.</li>
-                            </ul>
-                            <p>Providing good documentation for libraries, classes, functions, and other API elements improves code readability and helps developers find and use your API. Document at least 20% of the public API elements.</p>
                           </div>
                         </div>
                       </div>
@@ -533,7 +543,7 @@ <h3>
               </div>
               <div class="packages-score packages-score-health">
                 <div class="packages-score-value -has-value">
-                  <span class="packages-score-value-number">110</span>
+                  <span class="packages-score-value-number">120</span>
                   <span class="packages-score-value-sign"></span>
                 </div>
                 <div class="packages-score-label">pub points</div>
@@ -619,7 +629,7 @@ <h3 class="detail-metadata-title">
             </div>
             <div class="packages-score packages-score-health">
               <div class="packages-score-value -has-value">
-                <span class="packages-score-value-number">110</span>
+                <span class="packages-score-value-number">120</span>
                 <span class="packages-score-value-sign"></span>
               </div>
               <div class="packages-score-label">pub points</div>

diff --git a/app/test/task/testdata/goldens/packages/oxygen/versions.html b/app/test/task/testdata/goldens/packages/oxygen/versions.html
@@ -296,7 +296,7 @@ <h2 id="stable">Stable versions of oxygen</h2>
               </div>
               <div class="packages-score packages-score-health">
                 <div class="packages-score-value -has-value">
-                  <span class="packages-score-value-number">110</span>
+                  <span class="packages-score-value-number">120</span>
                   <span class="packages-score-value-sign"></span>
                 </div>
                 <div class="packages-score-label">pub points</div>
@@ -382,7 +382,7 @@ <h3 class="detail-metadata-title">
             </div>
             <div class="packages-score packages-score-health">
               <div class="packages-score-value -has-value">
-                <span class="packages-score-value-number">110</span>
+                <span class="packages-score-value-number">120</span>
                 <span class="packages-score-value-sign"></span>
               </div>
               <div class="packages-score-label">pub points</div>

diff --git a/app/test/task/testdata/goldens/packages/oxygen/versions/1.0.0.html b/app/test/task/testdata/goldens/packages/oxygen/versions/1.0.0.html
@@ -238,7 +238,7 @@ <h1 class="hash-header" id="oxygen">
               </div>
               <div class="packages-score packages-score-health">
                 <div class="packages-score-value -has-value">
-                  <span class="packages-score-value-number">110</span>
+                  <span class="packages-score-value-number">120</span>
                   <span class="packages-score-value-sign"></span>
                 </div>
                 <div class="packages-score-label">pub points</div>
@@ -324,7 +324,7 @@ <h3 class="detail-metadata-title">
             </div>
             <div class="packages-score packages-score-health">
               <div class="packages-score-value -has-value">
-                <span class="packages-score-value-number">110</span>
+                <span class="packages-score-value-number">120</span>
                 <span class="packages-score-value-sign"></span>
               </div>
               <div class="packages-score-label">pub points</div>

diff --git a/app/test/task/testdata/goldens/packages/oxygen/versions/1.0.0/changelog.html b/app/test/task/testdata/goldens/packages/oxygen/versions/1.0.0/changelog.html
@@ -244,7 +244,7 @@ <h2 class="changelog-version hash-header" id="100">
               </div>
               <div class="packages-score packages-score-health">
                 <div class="packages-score-value -has-value">
-                  <span class="packages-score-value-number">110</span>
+                  <span class="packages-score-value-number">120</span>
                   <span class="packages-score-value-sign"></span>
                 </div>
                 <div class="packages-score-label">pub points</div>
@@ -330,7 +330,7 @@ <h3 class="detail-metadata-title">
             </div>
             <div class="packages-score packages-score-health">
               <div class="packages-score-value -has-value">
-                <span class="packages-score-value-number">110</span>
+                <span class="packages-score-value-number">120</span>
                 <span class="packages-score-value-sign"></span>
               </div>
               <div class="packages-score-label">pub points</div>

diff --git a/app/test/task/testdata/goldens/packages/oxygen/versions/1.0.0/example.html b/app/test/task/testdata/goldens/packages/oxygen/versions/1.0.0/example.html
@@ -239,7 +239,7 @@ <h3 class="detail-lead-title">Metadata</h3>
               </div>
               <div class="packages-score packages-score-health">
                 <div class="packages-score-value -has-value">
-                  <span class="packages-score-value-number">110</span>
+                  <span class="packages-score-value-number">120</span>
                   <span class="packages-score-value-sign"></span>
                 </div>
                 <div class="packages-score-label">pub points</div>
@@ -325,7 +325,7 @@ <h3 class="detail-metadata-title">
             </div>
             <div class="packages-score packages-score-health">
               <div class="packages-score-value -has-value">
-                <span class="packages-score-value-number">110</span>
+                <span class="packages-score-value-number">120</span>
                 <span class="packages-score-value-sign"></span>
               </div>
               <div class="packages-score-label">pub points</div>

diff --git a/app/test/task/testdata/goldens/packages/oxygen/versions/1.0.0/install.html b/app/test/task/testdata/goldens/packages/oxygen/versions/1.0.0/install.html
@@ -267,7 +267,7 @@ <h3>Import it</h3>
               </div>
               <div class="packages-score packages-score-health">
                 <div class="packages-score-value -has-value">
-                  <span class="packages-score-value-number">110</span>
+                  <span class="packages-score-value-number">120</span>
                   <span class="packages-score-value-sign"></span>
                 </div>
                 <div class="packages-score-label">pub points</div>
@@ -353,7 +353,7 @@ <h3 class="detail-metadata-title">
             </div>
             <div class="packages-score packages-score-health">
               <div class="packages-score-value -has-value">
-                <span class="packages-score-value-number">110</span>
+                <span class="packages-score-value-number">120</span>
                 <span class="packages-score-value-sign"></span>
               </div>
               <div class="packages-score-label">pub points</div>

diff --git a/app/test/task/testdata/goldens/packages/oxygen/versions/1.0.0/license.html b/app/test/task/testdata/goldens/packages/oxygen/versions/1.0.0/license.html
@@ -240,7 +240,7 @@ <h2>License</h2>
               </div>
               <div class="packages-score packages-score-health">
                 <div class="packages-score-value -has-value">
-                  <span class="packages-score-value-number">110</span>
+                  <span class="packages-score-value-number">120</span>
                   <span class="packages-score-value-sign"></span>
                 </div>
                 <div class="packages-score-label">pub points</div>
@@ -326,7 +326,7 @@ <h3 class="detail-metadata-title">
             </div>
             <div class="packages-score packages-score-health">
               <div class="packages-score-value -has-value">
-                <span class="packages-score-value-number">110</span>
+                <span class="packages-score-value-number">120</span>
                 <span class="packages-score-value-sign"></span>
               </div>
               <div class="packages-score-label">pub points</div>