API doc for pipes

[jbogarthyde]

PR Checklist

Please check if your PR fulfills the following requirements:

• The commit message follows our guidelines: https://github.com/angular/angular/blob/master/CONTRIBUTING.md#commit
• Tests for the changes have been added (for bug fixes / features)
• Docs have been added / updated (for bug fixes / features)

PR Type

What kind of change does this PR introduce?

[ ] Bugfix
[ ] Feature
[ ] Code style update (formatting, local variables)
[ ] Refactoring (no functional changes, no api changes)
[ ] Build related changes
[ ] CI related changes
[x] Documentation content changes
[ ] angular.io application / infrastructure changes
[ ] Other... Please describe:

Does this PR introduce a breaking change?

[ ] Yes
[x] No
 

[jbogarthyde]

@petebacondarwin FYI

[mary-poppins]

You can preview f8e6cbb at https://pr24141-f8e6cbb.ngbuilds.io/.

[mary-poppins]

You can preview e3d0b77 at https://pr24141-e3d0b77.ngbuilds.io/.

[mary-poppins]

You can preview db133ab at https://pr24141-db133ab.ngbuilds.io/.

[mary-poppins]

You can preview c06c867 at https://pr24141-c06c867.ngbuilds.io/.

[mary-poppins]

You can preview dd0d78c at https://pr24141-dd0d78c.ngbuilds.io/.

[mary-poppins]

You can preview 4b9b3c3 at https://pr24141-4b9b3c3.ngbuilds.io/.

[jenniferfell]

Approved with one change: Please change to "deprecated in v5" or similar (v "from v5").

Other comments....Please file an issue against caps style in auto-generated headings. Of my other comments, the rest are minor editorial.

[jenniferfell]

whitespace-separated word

[jenniferfell]

lower case.

[jenniferfell]

No comma when second clause is dependent. "The pipe uses the Internationalization API and is therefore only reliable in Chrome and Opera browsers."

[jenniferfell]

reevaluated

[jenniferfell]

"and so on" - delete? change to "or other formatting characteristics"?

[jenniferfell]

Predefined (one word)

[jenniferfell]

Did you want en-US in single quotes or backticks or none? Above "en-US locale" has no special treatment. Let's standardize how to handle locale names. You choose.

[jenniferfell]

I think we should use sentence case in table column headers, so it matches heading cap style everywhere else in docs.

[jenniferfell]

Need to file an issue. Usage notes heading should be sentence caps, not title caps.

[jenniferfell]

Need to file an issue. Input values heading should be sentence caps, not title caps.

[jenniferfell]

@jbogarthyde If this is no longer just to test the new template and generator, pls update the title. Thanks!

[mary-poppins]

You can preview e2b9786 at https://pr24141-e2b9786.ngbuilds.io/.

[jbogarthyde]

We are still testing the template, leaving title alone.

[mary-poppins]

You can preview 1595762 at https://pr24141-1595762.ngbuilds.io/.

[mary-poppins]

You can preview de04249 at https://pr24141-de04249.ngbuilds.io/.

[mary-poppins]

You can preview 46097e4 at https://pr24141-46097e4.ngbuilds.io/.

[vicb]

I would replace

+   * @param value The string to transform, with words delimited by any whitespace character,
+   * such a space, tab, or line-feed character.

with

+   * @param value The text to convert to lower case.

I don't think trying to define what a "word" is helps and I'm not sure if this is correct definition anyway.

[vicb]

Not adressed

[jbogarthyde]

oops - wrong one, this should only be in title-case. Removing it.

[vicb]

Sounds like we are repeating the same thing twice ?
Replace whitespace-separated word with word as the former is wrong.

[vicb]

Not sure how this get rendered but the text itself adds no value IMO.

[jbogarthyde]

It is a general rule of our new API guidelines that all code examples should be introduced with a text description of what the code is an example of. In this case, it doesn't add a whole lot of value, but it is still required.

[jbogarthyde]

Most code examples show some specific thing -- it helps the reader know where to look in the code if you first tell them what it is supposed to show. This is part of reducing cognitive load for the reader, by making each point as explicit as possible.

[vicb]

same comment as earlier. I would use @param value The text to convert to title case

[gkalpak]

For TitleCasePipe it might be valueable to explicitly mention that whitespace is used as the separator, especially since the behavior was different in the past (e.g. - where treated as boundaries, but not any more).

[vicb]

ditto

[vicb]

not adressed.

[vicb]

👍

[vicb]

still confusing/wrong.
each locale has 2 sets of data: the "regular" one and the "extra" one. * means the extra one, this is what the former description stated.

[jbogarthyde]

OK, got it.

[vicb]

in the _local_ time this was important too

[vicb]

Thanks for the updates.
A few more comments

[mary-poppins]

You can preview a4f7473 at https://pr24141-a4f7473.ngbuilds.io/.

[jbogarthyde]

Addressed comments, and some more small fixes.

[mary-poppins]

You can preview de33116 at https://pr24141-de33116.ngbuilds.io/.

[mary-poppins]

You can preview 449373b at https://pr24141-449373b.ngbuilds.io/.

[jbogarthyde]

@vicb @ocombe
I believe I have made all your requested changes. I think this can go green if you both remove your "changes requested" status, and vic can do pull-approve.
Travis build appears to be failing for unrelated reasons - the preview built fine.
Please let me know if there is anything else I need to do to get this landed.

[mhevery]

http://test/OCL:201573473:BASE:201573500:1529611895746:6c6cb57

Comments addressed, Vic on vacation.

[cexbrayat]

If I may (and @ocombe will correct me if I'm wrong), I think the docs for the currency pipe should also mention that if digitsInfo is not provided, then the format is determined by the pipe itself based on the currency: {{ 14 | currency:'CAD' }} gives $CA14.00, whereas {{ 14 | currency:'CLP' }} gives CLP14 because chilean pesos don't have cents.
Or maybe that should be in https://github.com/angular/angular/blob/master/packages/examples/common/pipes/ts/currency_pipe.ts I don't know.

I can submit a PR if you agree (unrelated, but I think there is an error in the example https://github.com/angular/angular/blob/master/packages/examples/common/pipes/ts/currency_pipe.ts#L21)

[ocombe]

That is true, the number of digits for rounding depends on the locale

[cexbrayat]

@ocombe 👍 I pushed #24661 to make it more obvious in the docs, added an example and fix an error with a current one. Let me know what you think when you have the occasion.

[angular-automatic-lock-bot]

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