build(docs-infra): add sealed markers to classes in API pages (#42807)

This change will mark classes as `sealed` unless they have been annotated
with an `@extensible` jsdoc tag.

Fixes #42802

PR Close #42807

aio/src/styles/2-modules/api-pages/_api-pages.scss

@@ -97,7 +97,6 @@
 
         .github-links {
           a {
-
             .material-icons:hover {
               background: none;
             }
@@ -167,6 +166,10 @@
     margin-top: 8px;
   }
 
+  .final-message {
+    font-style: italic;
+  }
+
   .api-heading {
     @include mixins.font-size(14);
     margin: 16px;

aio/src/styles/2-modules/label/_label-theme.scss

@@ -8,9 +8,17 @@
     &.api-status-label {
       background-color: constants.$mediumgray;
 
-      &.deprecated, &.security, &.impure-pipe {
+      &.deprecated,
+      &.security,
+      &.impure-pipe {
         background-color: constants.$brightred;
       }
+
+      a {
+        color: inherit;
+        line-height: inherit;
+        font-size: inherit;
+      }
     }
 
     &.api-type-label {

aio/tools/transforms/angular-api-package/tag-defs/extensible.js

@@ -0,0 +1,11 @@
+/**
+ * Use this tag to indicate that this class can be extended.
+ *
+ * This is the opposite of the Java `sealed` keyword.
+ */
+module.exports = function() {
+  return {
+    name: 'extensible',
+    transforms: function() { return true; }
+  };
+};

aio/tools/transforms/templates/api/base.template.html

@@ -26,6 +26,9 @@
     {% if doc.deprecated !== undefined %}<label class="api-status-label deprecated">deprecated</label>{% endif %}
     {% if doc.security !== undefined %}<label class="api-status-label security">security</label>{% endif %}
     {% if doc.pipeOptions.pure === 'false' %}<label class="api-status-label impure-pipe">impure</label>{% endif %}
+    {% if doc.docType === 'class' and doc.extensible !== true and not doc.isAbstract %}<label class="github-links api-status-label final" title="This class should not be extended.">
+      <a href="{$ github.githubVersionedUrl(versionInfo) $}/docs/PUBLIC_API.md#final-classes">final</a>
+    </label>{% endif %}
   </header>
   {% endblock %}
   <aio-toc class="embedded"></aio-toc>

aio/tools/transforms/templates/api/class.template.html

@@ -1,6 +1,5 @@
 {% import "lib/ngmodule.html" as ngModuleHelpers -%}
 {% extends 'export-base.template.html' -%}
-
 {% block overview %}
   {% include "includes/class-overview.html" %}
 {% endblock %}

aio/tools/transforms/templates/api/lib/memberHelpers.html

@@ -95,6 +95,14 @@
     {% if method.shortDescription %}<tr>
       <td class="short-description">
         {$ method.shortDescription | marked $}
+
+        {% if method.containerDoc.docType === 'class' and method.name === 'constructor' and not method.containerDoc.isAbstract and method.containerDoc.extensible !== true %}
+        <p class="final-message">
+          This class is "final" and should not be extended.
+          See the <a href="{$ github.githubVersionedUrl(versionInfo) $}/docs/PUBLIC_API.md#final-classes">public API notes</a>.
+        </p>
+        {% endif %}
+
         {%- if method.see.length %}
         <p>See also:</p>
         <ul>

aio/tools/transforms/templates/lib/githubLinks.html

@@ -2,17 +2,23 @@
 {$ fileInfo.realProjectRelativePath if fileInfo.realProjectRelativePath else fileInfo.projectRelativePath $}
 {%- endmacro %}
 
-{% macro githubViewHref(doc, versionInfo) -%}
-{% set githubUrl = 'https://github.com/' + versionInfo.gitRepoInfo.owner + '/' + versionInfo.gitRepoInfo.repo -%}
+{% macro githubBaseUrl(versionInfo) -%}
+https://github.com/{$ versionInfo.gitRepoInfo.owner $}/{$ versionInfo.gitRepoInfo.repo $}
+{%- endmacro %}
+
+{% macro githubVersionedUrl(versionInfo) -%}
 {% set version = versionInfo.currentVersion.isSnapshot and versionInfo.currentVersion.SHA or versionInfo.currentVersion.raw -%}
+{$ githubBaseUrl(versionInfo) $}/tree/{$ version $}
+{%- endmacro %}
+
+{% macro githubViewHref(doc, versionInfo) -%}
 {% set lineInfo = doc.startingLine and ('#L' + (doc.startingLine + 1) + '-L' + (doc.endingLine + 1)) or '' -%}
-{$ githubUrl $}/tree/{$ version $}/{$ projectRelativePath(doc.fileInfo) $}{$ lineInfo $}
+{$ githubVersionedUrl(versionInfo) $}/{$ projectRelativePath(doc.fileInfo) $}{$ lineInfo $}
 {%- endmacro %}
 
 {% macro githubEditHref(doc, versionInfo, pathPrefix) -%}
-{% set githubUrl = 'https://github.com/' + versionInfo.gitRepoInfo.owner + '/' + versionInfo.gitRepoInfo.repo -%}
 {% set lineInfo = doc.startingLine and ('#L' + (doc.startingLine + 1) + '-L' + (doc.endingLine + 1)) or '' -%}
-{$ githubUrl $}/edit/master/{$ projectRelativePath(doc.fileInfo) $}?message=docs
+{$ githubBaseUrl(versionInfo) $}/edit/master/{$ projectRelativePath(doc.fileInfo) $}?message=docs
   {%- if doc.moduleDoc %}({$ doc.moduleDoc.id.split('/')[0] $})
   {%- elseif doc.docType === 'module' %}({$ doc.id.split('/')[0] $})
   {%- elseif doc.docType === 'content' %}