Clarify docs for Collection interface

[DartBot]

This issue was originally filed by alexey.v.var...@gmail.com

---

The API documentation for corelib interface Collection (http://dart.googlecode.com/svn/trunk/dart/corelib/src/collection.dart) needs some clarifications.

The suggested patch fills in the gaps.

---

Attachment:
collection.patch (1.73 KB)

[DartBot]

This comment was originally written by ngeoffray@google.com

---

Hi Alexey,

I'm not sure the Collection interface needs these 'clarifications'. For example, if the collection is empty, you may not use the parameter at all, and adding an explicit check for the parameter being a closure is kind of wasteful.

A general statement that we should add to corelib is that passing in a wrong type will lead to undefined behavior.

As for the order, a 'Collection' does not know about any order. I'd rather talk about ordering in the List interface.

---

Set owner to ngeoffray@google.com.
Added Area-Library label.

[DartBot]

This comment was originally written by alexey.v.varlamov...@gmail.com

---

I agree that adding general statements somewhere would obviate the need to reiterate about things like ObjectNotClosureException. My guess is that "exceptions.dart" is the right candidate to place such general statements.

I certainly would not mind if you override some docs in the List interface, where additional semantics appears for inherited methods.

Still the following clarifications are desirable:

1. behavior of filter/every/some when this collection is empty.
2. behavior when argument function fails (throws exception), in forEach/filter/every/some (this was not in the patch).

Thanks for the prompt response, btw!

[DartBot]

This comment was originally written by alexey.v.var...@gmail.com

---

One more thought about the general statement: it is clear that there can't be absolute answer to invalid usage of APIs, yet it would be more friendly to hint which reaction one would normally expect for typical error conditions.
Much like "normative" vs "commentary" text in the specification.
Anyway, this would be a natural way to document corelib exception classes, which remain bare so far.

[DartBot]

This comment was originally written by drfibonacci@google.com

---

Added Triaged label.

[DartBot]

This comment was originally written by ngeoffray@google.com

---

Handing off to Josh.

---

Set owner to jjb@google.com.

[sethladd]

This is probably stale. Please re-open if you feel differently.

---

Removed the owner.
Added AssumedStale label.