Eliminate gaps in the documentation for List interface

[DartBot]

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

---

There are numerous gaps and uncertainties in the API documentation for List interface (http://dart.googlecode.com/svn/trunk/dart/corelib/src/list.dart) - nearly every method needs to be expanded upon.

The suggested patch fills in the gaps, it merely documents current implementation (except range-related methods which are not available yet).

---

Attachment:
list.patch (7.37 KB)

[DartBot]

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

---

Attachment:
list.patch (8.01 KB)

[DartBot]

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

---

Also, please clarify the intended behavior of copyFrom() in the case it invoked with the same list for source and destination (is it like Java's System.arraycopy()?).

[DartBot]

This comment was originally written by drfibonacci@google.com

---

Added Area-Library, Triaged labels.

[DartBot]

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

---

As the copyFrom() method was dropped in favor of setRange(), the question in comment #­3 now relates to the setRange.

Also, please clarify the behaviour of methods which may extend list in bulks, in case of exceeded memory limits - should one expect preventive OutOfMemoryException? These are the following methods: insertRange, set length, List([int len]).

[DartBot]

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

---

There is one more aspect which deserves clarification:
what kind of list (extendable or fixed size) is returned by methods getRange() and filter(). The latter could be better declared with covariant return type, btw.

[DartBot]

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

---

Here is an updated patch to latest trunk state.

---

Attachment:
list.patch (7.59 KB)

[lrhn]

I have gone through the List documentation and have tried to improve it where it is still lacking.

We are generally not saying when that passing "null" is an error. We take that to be the default, and are instead stating it in places where null is allowed.
Likewise, we don't want to overspecify the error types, and instead write simply "it is an error if ..." or "this and that must be ...". Not satisfying these requirements will throw an Error of some sort (usually an ArgumentError), just as passing the wrong type will throw an Error in checked mode.

---

Added Fixed label.