This sentence doesn't make any sense to me. The old text is better IMHO. Even when the annotation name was changed from ViewQuery to ViewChildren it is still a query. Using the name of the element to document as main part of the documentation doesn't provide much value anyway. ("Foo" "This is a Foo")

What about something like

"When a field is decorated with @ViewChildren() Angular assigns a QueryList containing references to the elements that match the name or type of the argument passed to @ViewChildren(). Changes in the DOM that affect resulting elements update the content of the QueryList." (I hope the last sentence is actually true, but I think so)

You're right. I'd like to use your sentence.

and, the last sentence is actually true. look at this! plunker

Same, I can't imagine anyone getting any idea what this is about from this description.

"When a field is decorated with @ViewChild() Angular assigns a component, directive or ElementRef to the field. When the parameter passed to @ViewChild() is a string, an element with a template variable with this name is looked up in the view and a reference to that element is assigned to the field. If a type is passed as argument a directive or component with that type is looked up in the view and if found a reference to the directive or component instance is assigned to the field."

Not sure this is 100% correct though. The information about the parameters also applies to @ViewChildren and should probably be added there too.

I'm wondering what happens when more elements match. Does it just assign the first it finds?

yes, thanks! I'll add a sentence to explain it.

@alexeagle why did we duplicate this? So that tools show the docs correctly when writing an example?

yes. in fact we have not duplicated enough - the properties of the object literal argument to our decorators don't have docs appearing in the editor

so, should I keep duplicated docs?

can you leave the TODO for me to fix this?

Okey!