build(aio): jsdoc tag changes #22401

petebacondarwin · 2018-02-23T13:52:18Z

mary-poppins · 2018-02-23T14:00:06Z

You can preview 4a9a812 at https://pr22401-4a9a812.ngbuilds.io/.

petebacondarwin · 2018-02-23T14:10:49Z

Here is a good example of the description splitting: https://pr22401-4a9a812.ngbuilds.io/api/animations/AnimationBuilder

The rendered docs look like:

While the original source code comment looks like:

mary-poppins · 2018-02-23T15:12:30Z

You can preview 4c56f8b at https://pr22401-4c56f8b.ngbuilds.io/.

mary-poppins · 2018-02-23T18:18:20Z

You can preview b4d9007 at https://pr22401-b4d9007.ngbuilds.io/.

mary-poppins · 2018-02-25T10:10:38Z

You can preview 9d42efc at https://pr22401-9d42efc.ngbuilds.io/.

mary-poppins · 2018-02-26T22:11:29Z

You can preview a138ceb at https://pr22401-a138ceb.ngbuilds.io/.

gkalpak · 2018-02-26T21:58:10Z

aio/tools/transforms/angular-api-package/processors/migrateLegacyJSDocTags.spec.js

+    expect(docs[2].description).toEqual('the description');
+  });
+
+  it('should ignore docs that have neither `howToUseIt` nor `whatItDoes` properties', () => {


howToUseIt --> howToUse 😁

gkalpak · 2018-02-26T22:02:51Z

aio/src/styles/0-base/_typography.scss

-  margin: 24px 0px 10px;
-  background: $lightgray;
-  clear: both;
-}


This change seems totally unrelated to this commit. Maybe move it in a separate one 😇
Also, there is one more h1:after style in _typography.scss and one in _marketing-layout.scss that are redundant now.

gkalpak · 2018-02-26T22:10:10Z

aio/tools/transforms/templates/api/includes/what-it-does.html

@@ -1,5 +0,0 @@
-{%- if doc.whatItDoes %}
-<div class="what-it-does info-banner">


If we don't use info-banner any more here, could we remove the corresponding CSS styles?

gkalpak · 2018-02-26T22:11:52Z

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

@@ -1,10 +1,10 @@
 {% extends 'base.template.html' -%}

 {% block body %}
-  {% include "includes/what-it-does.html" %}
+  <p class="short-description">{$ doc.shortDescription | marked $}</p>


Is it possible to not have shortDescription? In that case, would it be better to omit the <p> altogether?

#22401 (comment)

gkalpak · 2018-02-26T22:12:18Z

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

@@ -4,7 +4,7 @@
 {% extends 'base.template.html' -%}

 {% block body %}
-  <p>{$ doc.whatItDoes | marked $}</p>
+  <p class="short-description">{$ doc.shortDescription | marked $}</p>


Is it possible to not have shortDescription? In that case, would it be better to omit the <p> altogether?

I think that the short description will come under the "required" parts of the API docs.

gkalpak · 2018-02-26T22:13:38Z

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

@@ -0,0 +1,5 @@
+module.exports = function(log, createDocMessage) {


Unused deps 😁

gkalpak · 2018-02-26T22:18:16Z

aio/tools/transforms/angular-api-package/processors/splitDescription.js

+      docs.forEach(doc => {
+        if (this.docTypes.indexOf(doc.docType) !== -1 && doc.description !== undefined) {
+          const description = doc.description.trim();
+          const endOfParagraph = description.indexOf('\n\n');


Is it possible to have whitespace between the two \n?

That would be nasty 😠 but OK, I guess we can handle that too.

petebacondarwin · 2018-02-27T10:40:47Z

aio/tools/transforms/angular-api-package/processors/splitDescription.spec.js

+const processorFactory = require('./splitDescription');
+const Dgeni = require('dgeni');
+
+fdescribe('splitDescription processor', () => {


See angular#22135 (comment)

…howToUse` See angular#22135 (comment)

* The first paragraph is now split off into the `shortDescription` property. * Usage of `howToUse` and `whatItDoes` have been updated. * The "Overview" heading for class is removed as it is self-evident * The original horizontal rule styling below the main heading is removed as not part of the new design Closes angular#22385

… and `@howToUse`

mary-poppins · 2018-02-27T11:05:46Z

You can preview 5bd18b0 at https://pr22401-5bd18b0.ngbuilds.io/.

mary-poppins · 2018-02-27T11:05:51Z

You can preview 6d0e882 at https://pr22401-6d0e882.ngbuilds.io/.

gkalpak

💯

gkalpak · 2018-02-27T21:07:54Z

aio/src/styles/0-base/_typography.scss

@@ -60,13 +50,7 @@ h6 {
  clear: both;
 }

-h1 {
-  @media screen and (max-width: 600px) {
-    margin: 0;


Why remove this style?

Previously there was an underline beneath h1 tags. This underline was given the appropriate margin (8px 0) for the surrounding text. Now that the underline has gone the margins are set by the following rule.

That being said, I now see that this rule also removes margin from before the h1 on narrow screens so I will put that back in.

See last fixup commit 1443bfb

mary-poppins · 2018-02-28T10:52:30Z

You can preview 1443bfb at https://pr22401-1443bfb.ngbuilds.io/.

…howToUse` (#22401) See #22135 (comment) PR Close #22401

PR Close #22401

* The first paragraph is now split off into the `shortDescription` property. * Usage of `howToUse` and `whatItDoes` have been updated. * The "Overview" heading for class is removed as it is self-evident * The original horizontal rule styling below the main heading is removed as not part of the new design Closes #22385 PR Close #22401

PR Close #22401

See angular#22135 (comment) PR Close angular#22401

…howToUse` (angular#22401) See angular#22135 (comment) PR Close angular#22401

PR Close angular#22401

* The first paragraph is now split off into the `shortDescription` property. * Usage of `howToUse` and `whatItDoes` have been updated. * The "Overview" heading for class is removed as it is self-evident * The original horizontal rule styling below the main heading is removed as not part of the new design Closes angular#22385 PR Close angular#22401

PR Close angular#22401

angular-automatic-lock-bot · 2019-09-13T20:21:28Z

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.}

petebacondarwin added action: review The PR is still awaiting reviews from at least one requested reviewer comp: aio labels Feb 23, 2018

googlebot added the cla: yes label Feb 23, 2018

petebacondarwin added this to REVIEW in docs-infra Feb 23, 2018

petebacondarwin mentioned this pull request Feb 23, 2018

aio + docs/api: place examples after signature and params sections #22135

Closed

petebacondarwin force-pushed the aio-jsdoc-tag-structure branch from 4c56f8b to b4d9007 Compare February 23, 2018 18:02

petebacondarwin force-pushed the aio-jsdoc-tag-structure branch from b4d9007 to 9d42efc Compare February 25, 2018 10:02

petebacondarwin requested a review from gkalpak February 26, 2018 14:26

gkalpak requested changes Feb 26, 2018

View reviewed changes

petebacondarwin commented Feb 27, 2018

View reviewed changes

petebacondarwin added 13 commits February 27, 2018 10:48

build(aio): deprecate @howToUse and @whatItDoes tags

d16292d

See angular#22135 (comment)

build(aio): add processor to migrate legacy tags @whatItDoes and `@…

0d6fcc6

…howToUse` See angular#22135 (comment)

fix(aio): remove heading border

5a0cce5

style(aio): add newline between test blocks

edb6b69

fixup! build(aio): add processor to migrate legacy tags @whatItDoes…

445941e

… and `@howToUse`

fixup! build(aio): split the description property in API docs

b87ea26

fixup! build(aio): add processor to migrate legacy tags @whatItDoes…

24123b4

… and `@howToUse`

build(aio): add @usageNotes tag def for API docs

8d4b690

fixup! build(aio): split the description property in API docs

92b7e51

fixup! build(aio): add @usageNotes tag def for API docs

aa44e54

fixup! build(aio): add processor to migrate legacy tags @whatItDoes…

12feb55

… and `@howToUse`

fixup! build(aio): split the description property in API docs

cecb30e

petebacondarwin force-pushed the aio-jsdoc-tag-structure branch from a0a37e2 to 6d0e882 Compare February 27, 2018 10:57

fixup! build(aio): split the description property in API docs

5bd18b0

gkalpak approved these changes Feb 27, 2018

View reviewed changes

gkalpak added action: cleanup The PR is in need of cleanup, either due to needing a rebase or in response to comments from reviews and removed action: review The PR is still awaiting reviews from at least one requested reviewer labels Feb 27, 2018

fixup! fix(aio): remove heading border

1443bfb

petebacondarwin added target: major This PR is targeted for the next major release action: merge The PR is ready for merge by the caretaker and removed action: cleanup The PR is in need of cleanup, either due to needing a rebase or in response to comments from reviews labels Feb 28, 2018

petebacondarwin moved this from REVIEW to MERGE in docs-infra Feb 28, 2018

alexeagle closed this in e75f0ce Feb 28, 2018

alexeagle pushed a commit that referenced this pull request Feb 28, 2018

build(aio): add processor to migrate legacy tags @whatItDoes and `@…

b924ce3

…howToUse` (#22401) See #22135 (comment) PR Close #22401

alexeagle pushed a commit that referenced this pull request Feb 28, 2018

fix(aio): remove heading border (#22401)

11264e2

PR Close #22401

alexeagle pushed a commit that referenced this pull request Feb 28, 2018

style(aio): add newline between test blocks (#22401)

11f30fc

PR Close #22401

alexeagle pushed a commit that referenced this pull request Feb 28, 2018

build(aio): add @usageNotes tag def for API docs (#22401)

7d65356

PR Close #22401

petebacondarwin removed this from MERGE in docs-infra Feb 28, 2018

leo6104 pushed a commit to leo6104/angular that referenced this pull request Mar 25, 2018

build(aio): deprecate @howToUse and @whatItDoes tags (angular#22401)

0873c86

See angular#22135 (comment) PR Close angular#22401

leo6104 pushed a commit to leo6104/angular that referenced this pull request Mar 25, 2018

build(aio): add processor to migrate legacy tags @whatItDoes and `@…

296927a

…howToUse` (angular#22401) See angular#22135 (comment) PR Close angular#22401

leo6104 pushed a commit to leo6104/angular that referenced this pull request Mar 25, 2018

fix(aio): remove heading border (angular#22401)

8df1480

PR Close angular#22401

leo6104 pushed a commit to leo6104/angular that referenced this pull request Mar 25, 2018

style(aio): add newline between test blocks (angular#22401)

b610008

PR Close angular#22401

leo6104 pushed a commit to leo6104/angular that referenced this pull request Mar 25, 2018

build(aio): add @usageNotes tag def for API docs (angular#22401)

92c65b1

PR Close angular#22401

petebacondarwin deleted the aio-jsdoc-tag-structure branch July 18, 2018 07:26

angular-automatic-lock-bot bot locked and limited conversation to collaborators Sep 13, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

build(aio): jsdoc tag changes #22401

build(aio): jsdoc tag changes #22401

petebacondarwin commented Feb 23, 2018

mary-poppins commented Feb 23, 2018

petebacondarwin commented Feb 23, 2018

mary-poppins commented Feb 23, 2018

mary-poppins commented Feb 23, 2018

mary-poppins commented Feb 25, 2018

mary-poppins commented Feb 26, 2018

gkalpak Feb 26, 2018

gkalpak Feb 26, 2018

gkalpak Feb 26, 2018

gkalpak Feb 26, 2018

petebacondarwin Feb 26, 2018

gkalpak Feb 26, 2018

petebacondarwin Feb 26, 2018

gkalpak Feb 26, 2018

gkalpak Feb 26, 2018

petebacondarwin Feb 26, 2018

petebacondarwin Feb 27, 2018

mary-poppins commented Feb 27, 2018

mary-poppins commented Feb 27, 2018

gkalpak left a comment

gkalpak Feb 27, 2018

petebacondarwin Feb 28, 2018

petebacondarwin Feb 28, 2018

mary-poppins commented Feb 28, 2018

angular-automatic-lock-bot bot commented Sep 13, 2019

		@@ -1,5 +0,0 @@
		{%- if doc.whatItDoes %}
		<div class="what-it-does info-banner">

		@@ -0,0 +1,5 @@
		module.exports = function(log, createDocMessage) {

build(aio): jsdoc tag changes #22401

build(aio): jsdoc tag changes #22401

Conversation

petebacondarwin commented Feb 23, 2018

mary-poppins commented Feb 23, 2018

petebacondarwin commented Feb 23, 2018

mary-poppins commented Feb 23, 2018

mary-poppins commented Feb 23, 2018

mary-poppins commented Feb 25, 2018

mary-poppins commented Feb 26, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mary-poppins commented Feb 27, 2018

mary-poppins commented Feb 27, 2018

gkalpak left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mary-poppins commented Feb 28, 2018

angular-automatic-lock-bot bot commented Sep 13, 2019