Skip to content

Commit e4e98ed

Browse files
petebacondarwindylhunn
petebacondarwin
authored and
dylhunn
committed
build(docs-infra): add sealed markers to classes in API pages (angular#42807)
This change will mark classes as `sealed` unless they have been annotated with an `@extensible` jsdoc tag. Fixes angular#42802 PR Close angular#42807
1 parent ec4dcdf commit e4e98ed

8 files changed

Lines changed: 54 additions & 8 deletions

File tree

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

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -97,7 +97,6 @@
9797

9898
.github-links {
9999
a {
100-
101100
.material-icons:hover {
102101
background: none;
103102
}
@@ -167,6 +166,10 @@
167166
margin-top: 8px;
168167
}
169168

169+
.final-message {
170+
font-style: italic;
171+
}
172+
170173
.api-heading {
171174
@include mixins.font-size(14);
172175
margin: 16px;

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

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,17 @@
88
&.api-status-label {
99
background-color: constants.$mediumgray;
1010

11-
&.deprecated, &.security, &.impure-pipe {
11+
&.deprecated,
12+
&.security,
13+
&.impure-pipe {
1214
background-color: constants.$brightred;
1315
}
16+
17+
a {
18+
color: inherit;
19+
line-height: inherit;
20+
font-size: inherit;
21+
}
1422
}
1523

1624
&.api-type-label {

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

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
/**
2+
* Use this tag to indicate that this class can be extended.
3+
*
4+
* This is the opposite of the Java `sealed` keyword.
5+
*/
6+
module.exports = function() {
7+
return {
8+
name: 'extensible',
9+
transforms: function() { return true; }
10+
};
11+
};

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

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,9 @@ <h1>{$ doc.name | escape $}</h1>
2626
{% if doc.deprecated !== undefined %}<label class="api-status-label deprecated">deprecated</label>{% endif %}
2727
{% if doc.security !== undefined %}<label class="api-status-label security">security</label>{% endif %}
2828
{% if doc.pipeOptions.pure === 'false' %}<label class="api-status-label impure-pipe">impure</label>{% endif %}
29+
{% 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.">
30+
<a href="{$ github.githubVersionedUrl(versionInfo) $}/docs/PUBLIC_API.md#final-classes">final</a>
31+
</label>{% endif %}
2932
</header>
3033
{% endblock %}
3134
<aio-toc class="embedded"></aio-toc>

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

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,5 @@
11
{% import "lib/ngmodule.html" as ngModuleHelpers -%}
22
{% extends 'export-base.template.html' -%}
3-
43
{% block overview %}
54
{% include "includes/class-overview.html" %}
65
{% endblock %}

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

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -95,6 +95,14 @@ <h3>
9595
{% if method.shortDescription %}<tr>
9696
<td class="short-description">
9797
{$ method.shortDescription | marked $}
98+
99+
{% if method.containerDoc.docType === 'class' and method.name === 'constructor' and not method.containerDoc.isAbstract and method.containerDoc.extensible !== true %}
100+
<p class="final-message">
101+
This class is "final" and should not be extended.
102+
See the <a href="{$ github.githubVersionedUrl(versionInfo) $}/docs/PUBLIC_API.md#final-classes">public API notes</a>.
103+
</p>
104+
{% endif %}
105+
98106
{%- if method.see.length %}
99107
<p>See also:</p>
100108
<ul>

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

Lines changed: 11 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,17 +2,23 @@
22
{$ fileInfo.realProjectRelativePath if fileInfo.realProjectRelativePath else fileInfo.projectRelativePath $}
33
{%- endmacro %}
44

5-
{% macro githubViewHref(doc, versionInfo) -%}
6-
{% set githubUrl = 'https://github.com/' + versionInfo.gitRepoInfo.owner + '/' + versionInfo.gitRepoInfo.repo -%}
5+
{% macro githubBaseUrl(versionInfo) -%}
6+
https://github.com/{$ versionInfo.gitRepoInfo.owner $}/{$ versionInfo.gitRepoInfo.repo $}
7+
{%- endmacro %}
8+
9+
{% macro githubVersionedUrl(versionInfo) -%}
710
{% set version = versionInfo.currentVersion.isSnapshot and versionInfo.currentVersion.SHA or versionInfo.currentVersion.raw -%}
11+
{$ githubBaseUrl(versionInfo) $}/tree/{$ version $}
12+
{%- endmacro %}
13+
14+
{% macro githubViewHref(doc, versionInfo) -%}
815
{% set lineInfo = doc.startingLine and ('#L' + (doc.startingLine + 1) + '-L' + (doc.endingLine + 1)) or '' -%}
9-
{$ githubUrl $}/tree/{$ version $}/{$ projectRelativePath(doc.fileInfo) $}{$ lineInfo $}
16+
{$ githubVersionedUrl(versionInfo) $}/{$ projectRelativePath(doc.fileInfo) $}{$ lineInfo $}
1017
{%- endmacro %}
1118

1219
{% macro githubEditHref(doc, versionInfo, pathPrefix) -%}
13-
{% set githubUrl = 'https://github.com/' + versionInfo.gitRepoInfo.owner + '/' + versionInfo.gitRepoInfo.repo -%}
1420
{% set lineInfo = doc.startingLine and ('#L' + (doc.startingLine + 1) + '-L' + (doc.endingLine + 1)) or '' -%}
15-
{$ githubUrl $}/edit/master/{$ projectRelativePath(doc.fileInfo) $}?message=docs
21+
{$ githubBaseUrl(versionInfo) $}/edit/master/{$ projectRelativePath(doc.fileInfo) $}?message=docs
1622
{%- if doc.moduleDoc %}({$ doc.moduleDoc.id.split('/')[0] $})
1723
{%- elseif doc.docType === 'module' %}({$ doc.id.split('/')[0] $})
1824
{%- elseif doc.docType === 'content' %}

‎docs/PUBLIC_API.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,14 @@ We explicitly don't consider the following to be our public API surface:
4141

4242
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.
4343

44+
<a name="final-classes"></a>
45+
46+
## Extending Angular classes
47+
48+
All classes in Angular's public API are `final` (they should not be extended) unless explicitly stated in the API documentation.
49+
50+
Extending such `final` classes is not supported, since protected members and internal implementation may change outside of major releases.
51+
4452
<a name="golden-files"></a>
4553

4654
## Golden files

0 commit comments

Comments
 (0)