docs(common): migrate deprecated jsdoc tags #23062
Conversation
petebacondarwin
added
action: review
|
You can preview c41642d at https://pr23062-c41642d.ngbuilds.io/. |
| * @description | ||
| * | ||
| * Formats a number as percentage. | ||
| * Uses the function {@link formatPercent} to format a number as a percentage according | ||
| * to locale rules. | ||
| * | ||
| * Where: |
There was a problem hiding this comment.
In cases like this, the description reds fine in source code, but when this will be split up in the docs, the where:... part will be out of context.
There was a problem hiding this comment.
It's not actually as bad as you may think due to the params section being directly above...
But the next step is to move these descriptions into the actual parameters of the transform function.
I can do that in this PR too to show how it would work.
There was a problem hiding this comment.
It was just an example. I have seen it in another PR a few days ago.
My point is that people will write docs in a way that will read fine in the comment, but not so fine in the docs template.
Let's hope that all reviewers will actually look at the preview 😛
There was a problem hiding this comment.
True but that is true of all docs, right. Like putting bad headings or crazy tables.
We should just ensure that reviewers actually look at the preview.
I have updated all the Pipes to put the param descriptions in the right place as an example of how to do this.
If we keep the amount of "general" description that people have to write to a minimum then we should be able to control how it looks better. The worst scenarios are when people feel they have a blank canvas and start trying to do their own "formatting".
petebacondarwin
force-pushed
the
aio-update-common-docs
branch
from
b52b8b3
to
ec9ffab
Compare
|
You can preview b52b8b3 at https://pr23062-b52b8b3.ngbuilds.io/. |
|
You can preview ec9ffab at https://pr23062-ec9ffab.ngbuilds.io/. |
|
@petebacondarwin you'll need to update the public api guard (that is now part of the angular monorepo) to not complain about the missing |
IgorMinar
added
action: cleanup
In pipes the content of these tags is now generated automatically. In directives these tags have been converted to `@usageNotes` tags, but in the future me might find a way to generate that usage too.
We get the overview for the doc by splitting off the first paragraph.
petebacondarwin
force-pushed
the
aio-update-common-docs
branch
from
ec9ffab
to
394052f
Compare
petebacondarwin
added
action: review
IgorMinar
added
action: merge
We get the overview for the doc by splitting off the first paragraph. PR Close #23062
|
This issue has been automatically locked due to inactivity. Read more about our automatic conversation locking policy. This action has been performed automatically by a bot. |
No description provided.