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' %}

docs/PUBLIC_API.md

@@ -41,6 +41,14 @@ We explicitly don't consider the following to be our public API surface:
 
 Our peer dependencies (such as TypeScript, Zone.js, or RxJS) are not considered part of our API surface, but they are included in our SemVer policies. We might update the required version of any of these dependencies in minor releases if the update doesn't cause breaking changes for Angular applications. Peer dependency updates that result in non-trivial breaking changes must be deferred to major Angular releases.
 
+<a name="final-classes"></a>
+
+## Extending Angular classes
+
+All classes in Angular's public API are `final` (they should not be extended) unless explicitly stated in the API documentation.
+
+Extending such `final` classes is not supported, since protected members and internal implementation may change outside of major releases.
+
 <a name="golden-files"></a>
 
 ## Golden files