New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Copy edit: angular/guide/template-syntax.md #1200

Closed
wants to merge 1 commit into
base: master
from

Conversation

Projects
None yet
5 participants
@100percentlinen

100percentlinen commented Nov 24, 2017

I only managed to edit up to line 781. Overall, the content conformed pretty well to the Google dev style guide. And I didn't find any typos!

Copy edit: angular/guide/template-syntax.md
I only managed to edit up to line 781. Overall, the content conformed pretty well to the Google dev style guide. And I didn't find any typos!
@googlebot

This comment has been minimized.

Show comment
Hide comment
@googlebot

googlebot Nov 24, 2017

Thanks for your pull request. It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

📝 Please visit https://cla.developers.google.com/ to sign.

Once you've signed, please reply here (e.g. I signed it!) and we'll verify. Thanks.


  • If you've already signed a CLA, it's possible we don't have your GitHub username or you're using a different email address. Check your existing CLA data and verify that your email is set on your git commits.
  • If your company signed a CLA, they designated a Point of Contact who decides which employees are authorized to participate. You may need to contact the Point of Contact for your company and ask to be added to the group of authorized contributors. If you don't know who your Point of Contact is, direct the project maintainer to go/cla#troubleshoot.
  • In order to pass this check, please resolve this problem and have the pull request author add another comment and the bot will run again.

googlebot commented Nov 24, 2017

Thanks for your pull request. It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

📝 Please visit https://cla.developers.google.com/ to sign.

Once you've signed, please reply here (e.g. I signed it!) and we'll verify. Thanks.


  • If you've already signed a CLA, it's possible we don't have your GitHub username or you're using a different email address. Check your existing CLA data and verify that your email is set on your git commits.
  • If your company signed a CLA, they designated a Point of Contact who decides which employees are authorized to participate. You may need to contact the Point of Contact for your company and ask to be added to the group of authorized contributors. If you don't know who your Point of Contact is, direct the project maintainer to go/cla#troubleshoot.
  • In order to pass this check, please resolve this problem and have the pull request author add another comment and the bot will run again.

@googlebot googlebot added the cla: no label Nov 24, 2017

@sarahmaddox

Thank you so much for these edits! I've added a few comments that need addressing, either as part of this pull request (PR) or as an immediate follow-up PR.

@@ -125,7 +125,7 @@ it assigns this composite interpolated result to an **element or directive prope
You appear to be inserting the result between element tags and assigning it to attributes.
It's convenient to think so, and you rarely suffer for this mistake.
Though this is not exactly true. Interpolation is a special syntax that Angular converts into a
However, it's not exactly true. Interpolation is a special syntax that Angular converts into a

This comment has been minimized.

@sarahmaddox

sarahmaddox Nov 24, 2017

Contributor

How about this rewording of the paragraph:

From a quick glance at the syntax, it looks as if you're inserting the result between element tags and assigning it to attributes. That's a convenient way to think of what's happening, but it's not exactly true. Interpolation is a special syntax that Angular converts into a property binding. See the details below.

@sarahmaddox

sarahmaddox Nov 24, 2017

Contributor

How about this rewording of the paragraph:

From a quick glance at the syntax, it looks as if you're inserting the result between element tags and assigning it to attributes. That's a convenient way to think of what's happening, but it's not exactly true. Interpolation is a special syntax that Angular converts into a property binding. See the details below.

* [No visible side effects](#no-visible-side-effects)
* [Quick execution](#quick-execution)
* [Simplicity](#simplicity)
* [Idempotence](#idempotence)
The only exceptions to these guidelines should be in specific circumstances that you thoroughly understand.
The only exceptions to these guidelines are specific circumstances that you thoroughly understand.

This comment has been minimized.

@sarahmaddox

sarahmaddox Nov 24, 2017

Contributor

How about this:

If you make an exception to the above guidelines, make sure you thoroughly understand the circumstances.

@sarahmaddox

sarahmaddox Nov 24, 2017

Contributor

How about this:

If you make an exception to the above guidelines, make sure you thoroughly understand the circumstances.

You should never worry that reading a component value might change some other displayed value.
The view should be stable throughout a single rendering pass.
It ensures that reading a component value doesn't change some other displayed value.
The view is stable throughout a single rendering pass.

This comment has been minimized.

@sarahmaddox

sarahmaddox Nov 24, 2017

Contributor

I think "is" should be "must be".

@sarahmaddox

sarahmaddox Nov 24, 2017

Contributor

I think "is" should be "must be".

A property name or method call should be the norm.
A property name or method call is the norm.

This comment has been minimized.

@sarahmaddox

sarahmaddox Nov 24, 2017

Contributor

How about changing the sentence as follows:

In most situations, use a property name or method call.

@sarahmaddox

sarahmaddox Nov 24, 2017

Contributor

How about changing the sentence as follows:

In most situations, use a property name or method call.

Angular provides many kinds of data binding.
This guide covers most of them, after a high-level view of Angular data binding and its syntax.
Below is a high-level summary of Angular data binding and its syntax. It's followed by more detailed information about most of the data binding types that Angular provides.

This comment has been minimized.

@sarahmaddox

sarahmaddox Nov 24, 2017

Contributor

In general, we aim for a line length of 80 characters or fewer. A bit of deviation is OK (there are many longer lines in this file) but this particular line is quite long. Please split it into 3 lines like this:

Below is a high-level summary of Angular data binding and its syntax. It's
followed by more detailed information about most of the data binding types that
Angular provides.

@sarahmaddox

sarahmaddox Nov 24, 2017

Contributor

In general, we aim for a line length of 80 characters or fewer. A bit of deviation is OK (there are many longer lines in this file) but this particular line is quite long. Please split it into 3 lines like this:

Below is a high-level summary of Angular data binding and its syntax. It's
followed by more detailed information about most of the data binding types that
Angular provides.

Binding types can be grouped into three categories distinguished by the direction of data flow:
from the _source-to-view_, from _view-to-source_, and in the two-way sequence: _view-to-source-to-view_:
Binding types can be grouped into three categories based on the direction of data flow: _source-to-view_, _view-to-source_, and two-way sequence _view-to-source-to-view_.

This comment has been minimized.

@sarahmaddox

sarahmaddox Nov 24, 2017

Contributor

In general, we aim for a line length of 80 characters or fewer. A bit of deviation is OK (there are many longer lines in this file) but this particular line is quite long. Please split it into 3 lines like this:

Binding types can be grouped into three categories based on the direction of
data flow: source-to-view, view-to-source, and two-way sequence
view-to-source-to-view.

@sarahmaddox

sarahmaddox Nov 24, 2017

Contributor

In general, we aim for a line length of 80 characters or fewer. A bit of deviation is OK (there are many longer lines in this file) but this particular line is quite long. Please split it into 3 lines like this:

Binding types can be grouped into three categories based on the direction of
data flow: source-to-view, view-to-source, and two-way sequence
view-to-source-to-view.

Your intuition is incorrect! Your everyday HTML mental model is misleading.
In fact, once you start data binding, you are no longer working with HTML *attributes*. You aren't setting attributes.
You are setting the *properties* of DOM elements, components, and directives.
Your everyday HTML mental model is misleading. In fact, once you start data binding, you're no longer working with HTML *attributes*. You aren't setting attributes; you're setting the *properties* of DOM elements, components, and directives.

This comment has been minimized.

@sarahmaddox

sarahmaddox Nov 24, 2017

Contributor

In general, we aim for a line length of 80 characters or fewer. A bit of deviation is OK (there are many longer lines in this file) but this particular line is quite long. Please split it into 4 lines like this

Your everyday HTML mental model is misleading. In fact, once you start data
binding, you're no longer working with HTML attributes. You aren't
setting attributes; you're setting the properties of DOM elements, components,
and directives.

@sarahmaddox

sarahmaddox Nov 24, 2017

Contributor

In general, we aim for a line length of 80 characters or fewer. A bit of deviation is OK (there are many longer lines in this file) but this particular line is quite long. Please split it into 4 lines like this

Your everyday HTML mental model is misleading. In fact, once you start data
binding, you're no longer working with HTML attributes. You aren't
setting attributes; you're setting the properties of DOM elements, components,
and directives.

@@ -658,7 +654,7 @@ If the name fails to match a property of a known directive or element, Angular r
### Avoid side effects
As mentioned previously, evaluation of a template expression should have no visible side effects.
As mentioned previously, the evaluation of a template expression has no visible side effects.

This comment has been minimized.

@sarahmaddox

sarahmaddox Nov 24, 2017

Contributor

I think "has" should be "must have".

@sarahmaddox

sarahmaddox Nov 24, 2017

Contributor

I think "has" should be "must have".

@kwalrath

This comment has been minimized.

Show comment
Hide comment
@kwalrath

kwalrath Dec 6, 2017

Member

@100percentlinen will you be able to make the fixes that @sarahmaddox has suggested, or should I do it?

Member

kwalrath commented Dec 6, 2017

@100percentlinen will you be able to make the fixes that @sarahmaddox has suggested, or should I do it?

@kwalrath

This comment has been minimized.

Show comment
Hide comment
@kwalrath

kwalrath Dec 6, 2017

Member

Also, we'll need a signed CLA before we can accept this PR.

Member

kwalrath commented Dec 6, 2017

Also, we'll need a signed CLA before we can accept this PR.

@100percentlinen

This comment has been minimized.

Show comment
Hide comment
@100percentlinen

100percentlinen Dec 6, 2017

100percentlinen commented Dec 6, 2017

@googlebot

This comment has been minimized.

Show comment
Hide comment
@googlebot

googlebot Dec 6, 2017

CLAs look good, thanks!

googlebot commented Dec 6, 2017

CLAs look good, thanks!

@googlebot googlebot added cla: yes and removed cla: no labels Dec 6, 2017

@kwalrath

This comment has been minimized.

Show comment
Hide comment
@kwalrath

kwalrath Dec 11, 2017

Member

No worries, @sarahmaddox or I will make the fixes. Thanks very much for your contribution!

Member

kwalrath commented Dec 11, 2017

No worries, @sarahmaddox or I will make the fixes. Thanks very much for your contribution!

@kwalrath

This comment has been minimized.

Show comment
Hide comment
@kwalrath

kwalrath Dec 21, 2017

Member

Replaced by #1220.

Member

kwalrath commented Dec 21, 2017

Replaced by #1220.

@kwalrath kwalrath closed this Dec 21, 2017

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment