build(docs-infra): add `final` labels to classes in API pages #42807

petebacondarwin · 2021-07-09T15:34:36Z

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

Fixes #42802

For example:

mary-poppins · 2021-07-09T15:48:57Z

You can preview b4564e0 at https://pr42807-b4564e0.ngbuilds.io/.

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

mary-poppins · 2021-07-12T11:28:16Z

You can preview 755fdf2 at https://pr42807-755fdf2.ngbuilds.io/.

petebacondarwin · 2021-07-12T11:30:35Z

@gkalpak and @AndrewKushnir - I changed the label to final and made it a link. I am not sure this is a good UI though (to have one of these labels clickable). So I also tried out adding a line of boilerplate text under the short-description too.

For an example see https://pr42807-755fdf2.ngbuilds.io/api/forms/FormGroup

Please take a look and let me know your thoughts.

petebacondarwin · 2021-07-12T15:30:59Z

OK, third iteration: George and I thought that putting the "This class is "final"..." text in the short description drew too much attention to it, and would actually be more confusing.

So now, I have moved that text to the constructor's short description (if there is a constructor).

mary-poppins · 2021-07-12T15:34:55Z

You can preview 1717ccb at https://pr42807-1717ccb.ngbuilds.io/.

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

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

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

mary-poppins · 2021-07-14T17:56:18Z

You can preview 74291f7 at https://pr42807-74291f7.ngbuilds.io/.

mary-poppins · 2021-07-14T18:11:21Z

You can preview aef35d3 at https://pr42807-aef35d3.ngbuilds.io/.

AndrewKushnir

Looks great, thanks Pete 👍

gkalpak · 2021-07-15T12:11:24Z

Apart from that the only concrete class I could find that is designed to be extended is UpgradeComponent.
@gkalpak / @AndrewKushnir do you know of any others?

I don't 😃

mary-poppins · 2021-07-15T12:19:17Z

You can preview 4e253db at https://pr42807-4e253db.ngbuilds.io/.

gkalpak

One question. Otherwise lgtm 🚀

gkalpak · 2021-07-15T12:26:06Z

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

@@ -26,6 +26,9 @@ <h1>{$ doc.name | escape $}</h1>
    {% 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.">


What about other docTypes, such as ngmodule (see for example CommonModule) or directive (see for example NgIf)?

Don't we need to also mark them as "final" (even if they don't have a public constructor most of the time)?

(NOTE: If we change the logic here, the same changes should be applied in memberHelpers.html.)

Yeah - I decided that we should start with only classes, since they are more likely to feel like they can be extended. Also those kinds of classes are rendered in the docs in a way that doesn't make it so obvious that they are classes.

We can easily add that at a later stage if it looks useful.

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

This class is designed to be used as a base class. Therefore it should not be marked as `final` in the API docs.

petebacondarwin · 2021-08-17T15:12:32Z

@AndrewKushnir - can you override the presubmit check, since this PR only changes a comment in code that will be synched to G3?

mary-poppins · 2021-08-17T15:21:56Z

You can preview 5879ed9 at https://pr42807-5879ed9.ngbuilds.io/.

AndrewKushnir · 2021-08-17T16:14:43Z

can you override the presubmit check, since this PR only changes a comment in code that will be synched to G3?

@petebacondarwin done! I'm adding "merge-assistance" label and this PR should be ready for merge. Thanks for implementing that Pete 👍

AndrewKushnir · 2021-08-17T16:16:06Z

Merge-assistance: Pete has global docs approval permissions and this PR was reviewed and approved by 2 engineers, so this PR is ready for merge now.

) This class is designed to be used as a base class. Therefore it should not be marked as `final` in the API docs. PR Close #42807

This change will mark classes as `sealed` unless they have been annotated with an `@extensible` jsdoc tag. Fixes #42802 PR Close #42807

) This class is designed to be used as a base class. Therefore it should not be marked as `final` in the API docs. PR Close #42807

…lar#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

…ular#42807) This class is designed to be used as a base class. Therefore it should not be marked as `final` in the API docs. PR Close angular#42807

angular-automatic-lock-bot · 2021-09-17T16:09:24Z

This issue has been automatically locked due to inactivity.
Please file a new issue if you are encountering a similar or related problem.

Read more about our automatic conversation locking policy.

_{This action has been performed automatically by a bot.}

…lar#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

…ular#42807) This class is designed to be used as a base class. Therefore it should not be marked as `final` in the API docs. PR Close angular#42807

google-cla bot added the cla: yes label Jul 9, 2021

petebacondarwin added comp: docs-infra state: WIP target: patch This PR is targeted for the next patch release labels Jul 9, 2021

ngbot bot modified the milestone: Backlog Jul 9, 2021

petebacondarwin added the aio: preview label Jul 9, 2021

gkalpak approved these changes Jul 10, 2021

View reviewed changes

aio/tools/transforms/templates/api/base.template.html Outdated Show resolved Hide resolved

gkalpak added the action: cleanup The PR is in need of cleanup, either due to needing a rebase or in response to comments from reviews label Jul 10, 2021

petebacondarwin force-pushed the docs-infra-sealed branch from d7a1dc3 to 755fdf2 Compare July 12, 2021 11:19

petebacondarwin removed the action: cleanup The PR is in need of cleanup, either due to needing a rebase or in response to comments from reviews label Jul 12, 2021

petebacondarwin changed the title ~~build(docs-infra): add sealed markers to classes in API pages~~ build(docs-infra): add final labels to classes in API pages Jul 12, 2021

gkalpak approved these changes Jul 13, 2021

View reviewed changes

aio/src/styles/2-modules/api-pages/_api-pages.scss Outdated Show resolved Hide resolved

aio/tools/transforms/templates/api/lib/memberHelpers.html Outdated Show resolved Hide resolved

aio/tools/transforms/templates/api/base.template.html Outdated Show resolved Hide resolved

petebacondarwin force-pushed the docs-infra-sealed branch from 1717ccb to 74291f7 Compare July 14, 2021 17:46

petebacondarwin added action: review The PR is still awaiting reviews from at least one requested reviewer and removed state: WIP labels Jul 14, 2021

petebacondarwin requested review from gkalpak and AndrewKushnir July 14, 2021 17:48

AndrewKushnir approved these changes Jul 14, 2021

View reviewed changes

petebacondarwin marked this pull request as ready for review July 15, 2021 07:13

pullapprove bot requested a review from jelbourn July 15, 2021 07:13

petebacondarwin force-pushed the docs-infra-sealed branch from aef35d3 to ca08a54 Compare July 15, 2021 07:23

gkalpak approved these changes Jul 15, 2021

View reviewed changes

petebacondarwin requested review from IgorMinar and removed request for jelbourn July 22, 2021 11:46

petebacondarwin removed the action: review The PR is still awaiting reviews from at least one requested reviewer label Aug 17, 2021

petebacondarwin removed the request for review from IgorMinar August 17, 2021 15:10

pullapprove bot requested a review from jelbourn August 17, 2021 15:10

petebacondarwin added 2 commits August 17, 2021 16:11

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

c1de824

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

docs(upgrade): add @extensible to the UpgradeComponent class

5879ed9

This class is designed to be used as a base class. Therefore it should not be marked as `final` in the API docs.

petebacondarwin force-pushed the docs-infra-sealed branch from 4e253db to 5879ed9 Compare August 17, 2021 15:11

petebacondarwin added action: merge The PR is ready for merge by the caretaker action: presubmit The PR is in need of a google3 presubmit labels Aug 17, 2021

AndrewKushnir removed the action: presubmit The PR is in need of a google3 presubmit label Aug 17, 2021

AndrewKushnir added the merge: caretaker note Alert the caretaker performing the merge to check the PR for an out of normal action needed or note label Aug 17, 2021

dylhunn closed this in e4e98ed Aug 17, 2021

dylhunn pushed a commit that referenced this pull request Aug 17, 2021

docs(upgrade): add @extensible to the UpgradeComponent class (#42807

e9dd078

) This class is designed to be used as a base class. Therefore it should not be marked as `final` in the API docs. PR Close #42807

dylhunn pushed a commit that referenced this pull request Aug 17, 2021

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

38d51e4

This change will mark classes as `sealed` unless they have been annotated with an `@extensible` jsdoc tag. Fixes #42802 PR Close #42807

dylhunn pushed a commit that referenced this pull request Aug 17, 2021

docs(upgrade): add @extensible to the UpgradeComponent class (#42807

545972e

) This class is designed to be used as a base class. Therefore it should not be marked as `final` in the API docs. PR Close #42807

petebacondarwin deleted the docs-infra-sealed branch August 17, 2021 16:26

angular-automatic-lock-bot bot locked and limited conversation to collaborators Sep 17, 2021

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

build(docs-infra): add `final` labels to classes in API pages #42807

build(docs-infra): add `final` labels to classes in API pages #42807

petebacondarwin commented Jul 9, 2021 •

edited

Loading

mary-poppins commented Jul 9, 2021

mary-poppins commented Jul 12, 2021

petebacondarwin commented Jul 12, 2021

petebacondarwin commented Jul 12, 2021

mary-poppins commented Jul 12, 2021

mary-poppins commented Jul 14, 2021

mary-poppins commented Jul 14, 2021

AndrewKushnir left a comment

gkalpak commented Jul 15, 2021 •

edited

Loading

mary-poppins commented Jul 15, 2021

gkalpak left a comment

gkalpak Jul 15, 2021

petebacondarwin Jul 15, 2021

petebacondarwin commented Aug 17, 2021

mary-poppins commented Aug 17, 2021

AndrewKushnir commented Aug 17, 2021

AndrewKushnir commented Aug 17, 2021

angular-automatic-lock-bot bot commented Sep 17, 2021

build(docs-infra): add final labels to classes in API pages #42807

build(docs-infra): add final labels to classes in API pages #42807

Conversation

petebacondarwin commented Jul 9, 2021 • edited Loading

mary-poppins commented Jul 9, 2021

mary-poppins commented Jul 12, 2021

petebacondarwin commented Jul 12, 2021

petebacondarwin commented Jul 12, 2021

mary-poppins commented Jul 12, 2021

mary-poppins commented Jul 14, 2021

mary-poppins commented Jul 14, 2021

AndrewKushnir left a comment

Choose a reason for hiding this comment

gkalpak commented Jul 15, 2021 • edited Loading

mary-poppins commented Jul 15, 2021

gkalpak left a comment

Choose a reason for hiding this comment

gkalpak Jul 15, 2021

Choose a reason for hiding this comment

petebacondarwin Jul 15, 2021

Choose a reason for hiding this comment

petebacondarwin commented Aug 17, 2021

mary-poppins commented Aug 17, 2021

AndrewKushnir commented Aug 17, 2021

AndrewKushnir commented Aug 17, 2021

angular-automatic-lock-bot bot commented Sep 17, 2021

build(docs-infra): add `final` labels to classes in API pages #42807

build(docs-infra): add `final` labels to classes in API pages #42807

petebacondarwin commented Jul 9, 2021 •

edited

Loading

gkalpak commented Jul 15, 2021 •

edited

Loading