Switch from interfaces to abstract classes in dart:io.

Switch from interfaces to abstract classes in dart:io.

Add a bunch of default argument values to the abstract classes
so they are picked up by dartdoc.

R=sgjesse@google.com
BUG=

Committed: https://code.google.com/p/dart/source/detail?r=12484

[Søren Gjesse, 2012-09-18 09:34:16]

LGTM

Looks better - especially having the default values for optional arguments
documented using code is nice.

https://codereview.chromium.org/10938010/diff/1/runtime/bin/file.dart
File runtime/bin/file.dart (right):

https://codereview.chromium.org/10938010/diff/1/runtime/bin/file.dart#newcode129
runtime/bin/file.dart:129: * The default value for [mode] is [:FileMode.READ:].
No need for documentation of the default value.

https://codereview.chromium.org/10938010/diff/1/runtime/bin/file.dart#newcode139
runtime/bin/file.dart:139: * The default value for [mode] is [:FileMode.READ:].
Ditto.

https://codereview.chromium.org/10938010/diff/1/runtime/bin/file.dart#newcode176
runtime/bin/file.dart:176: * By default the mode is FileMode.WRITE.
Ditto.

https://codereview.chromium.org/10938010/diff/1/runtime/bin/file.dart#newcode194
runtime/bin/file.dart:194: * [encoding]. The default encoding is
[:Encoding.UTF_8:].
Ditto.

https://codereview.chromium.org/10938010/diff/1/runtime/bin/file.dart#newcode203
runtime/bin/file.dart:203: * given [encoding]. The default encoding is
[:Encoding.UTF_8:].
Ditto.

https://codereview.chromium.org/10938010/diff/1/runtime/bin/file.dart#newcode209
runtime/bin/file.dart:209: * [encoding]. The default encoding is
[:Encoding.UTF_8:].
Ditto.

https://codereview.chromium.org/10938010/diff/1/runtime/bin/file.dart#newcode219
runtime/bin/file.dart:219: * [:Encoding.UTF_8:].
Ditto.

https://codereview.chromium.org/10938010/diff/1/runtime/bin/file.dart#newcode299
runtime/bin/file.dart:299: * default encoding is UTF-8 - [:Encoding.UTF_8:].
Returns a
Ditto.

https://codereview.chromium.org/10938010/diff/1/runtime/bin/file.dart#newcode309
runtime/bin/file.dart:309: * written. The default encoding is UTF-8 -
[:Encoding.UTF_8:].
Ditto.

https://codereview.chromium.org/10938010/diff/1/runtime/bin/http.dart
File runtime/bin/http.dart (right):

https://codereview.chromium.org/10938010/diff/1/runtime/bin/http.dart#newcode397
runtime/bin/http.dart:397: * string.
No need for documentation of the default values.

https://codereview.chromium.org/10938010/diff/1/runtime/bin/input_stream.dart
File runtime/bin/input_stream.dart (right):

https://codereview.chromium.org/10938010/diff/1/runtime/bin/input_stream.dart...
runtime/bin/input_stream.dart:120: * encoding. The default encoding is UTF-8 -
`Encoding.UTF_8`.
No need for documentation of the default value.

https://codereview.chromium.org/10938010/diff/1/runtime/bin/process.dart
File runtime/bin/process.dart (right):

https://codereview.chromium.org/10938010/diff/1/runtime/bin/process.dart#newc...
runtime/bin/process.dart:35: [ProcessOptions options = null]) {
Isn't null the default default value for optional arguments ("= null" is
redundant)?

https://codereview.chromium.org/10938010/diff/1/runtime/bin/process.dart#newc...
runtime/bin/process.dart:44: * options other than the executable and the
arguments.
Maybe add these two lines on the options argument for start above as well.

https://codereview.chromium.org/10938010/diff/1/runtime/bin/process.dart#newc...
runtime/bin/process.dart:52: [ProcessOptions options = null]) {
"= null" needed?

https://codereview.chromium.org/10938010/diff/1/runtime/bin/process.dart#newc...
runtime/bin/process.dart:104: * signal giving, it'll have different meanings.
The default [signal] to
No need for documentation of the default value.

https://codereview.chromium.org/10938010/diff/1/tests/standalone/io/http_head...
File tests/standalone/io/http_headers_test.dart (right):

https://codereview.chromium.org/10938010/diff/1/tests/standalone/io/http_head...
tests/standalone/io/http_headers_test.dart:242: contentType = new
_ContentType("", "");
Replace new _ContentType("", "") with new ContentType().

[Mads Ager (google), 2012-09-18 10:46:39]

https://codereview.chromium.org/10938010/diff/1/runtime/bin/file.dart
File runtime/bin/file.dart (right):

https://codereview.chromium.org/10938010/diff/1/runtime/bin/file.dart#newcode129
runtime/bin/file.dart:129: * The default value for [mode] is [:FileMode.READ:].
On 2012/09/18 09:34:16, Søren Gjesse wrote:
> No need for documentation of the default value.

Done.

https://codereview.chromium.org/10938010/diff/1/runtime/bin/file.dart#newcode139
runtime/bin/file.dart:139: * The default value for [mode] is [:FileMode.READ:].
On 2012/09/18 09:34:16, Søren Gjesse wrote:
> Ditto.

Done.

https://codereview.chromium.org/10938010/diff/1/runtime/bin/file.dart#newcode176
runtime/bin/file.dart:176: * By default the mode is FileMode.WRITE.
On 2012/09/18 09:34:16, Søren Gjesse wrote:
> Ditto.

Done.

https://codereview.chromium.org/10938010/diff/1/runtime/bin/file.dart#newcode194
runtime/bin/file.dart:194: * [encoding]. The default encoding is
[:Encoding.UTF_8:].
On 2012/09/18 09:34:16, Søren Gjesse wrote:
> Ditto.

Done.

https://codereview.chromium.org/10938010/diff/1/runtime/bin/file.dart#newcode203
runtime/bin/file.dart:203: * given [encoding]. The default encoding is
[:Encoding.UTF_8:].
On 2012/09/18 09:34:16, Søren Gjesse wrote:
> Ditto.

Done.

https://codereview.chromium.org/10938010/diff/1/runtime/bin/file.dart#newcode209
runtime/bin/file.dart:209: * [encoding]. The default encoding is
[:Encoding.UTF_8:].
On 2012/09/18 09:34:16, Søren Gjesse wrote:
> Ditto.

Done.

https://codereview.chromium.org/10938010/diff/1/runtime/bin/file.dart#newcode219
runtime/bin/file.dart:219: * [:Encoding.UTF_8:].
On 2012/09/18 09:34:16, Søren Gjesse wrote:
> Ditto.

Done.

https://codereview.chromium.org/10938010/diff/1/runtime/bin/file.dart#newcode299
runtime/bin/file.dart:299: * default encoding is UTF-8 - [:Encoding.UTF_8:].
Returns a
On 2012/09/18 09:34:16, Søren Gjesse wrote:
> Ditto.

Done.

https://codereview.chromium.org/10938010/diff/1/runtime/bin/file.dart#newcode309
runtime/bin/file.dart:309: * written. The default encoding is UTF-8 -
[:Encoding.UTF_8:].
On 2012/09/18 09:34:16, Søren Gjesse wrote:
> Ditto.

Done.

https://codereview.chromium.org/10938010/diff/1/runtime/bin/http.dart
File runtime/bin/http.dart (right):

https://codereview.chromium.org/10938010/diff/1/runtime/bin/http.dart#newcode397
runtime/bin/http.dart:397: * string.
On 2012/09/18 09:34:16, Søren Gjesse wrote:
> No need for documentation of the default values.

Done.

https://codereview.chromium.org/10938010/diff/1/runtime/bin/input_stream.dart
File runtime/bin/input_stream.dart (right):

https://codereview.chromium.org/10938010/diff/1/runtime/bin/input_stream.dart...
runtime/bin/input_stream.dart:120: * encoding. The default encoding is UTF-8 -
`Encoding.UTF_8`.
On 2012/09/18 09:34:16, Søren Gjesse wrote:
> No need for documentation of the default value.

Done.

https://codereview.chromium.org/10938010/diff/1/runtime/bin/process.dart
File runtime/bin/process.dart (right):

https://codereview.chromium.org/10938010/diff/1/runtime/bin/process.dart#newc...
runtime/bin/process.dart:35: [ProcessOptions options = null]) {
On 2012/09/18 09:34:16, Søren Gjesse wrote:
> Isn't null the default default value for optional arguments ("= null" is
> redundant)?

Yes, it is redundant. Removed.

https://codereview.chromium.org/10938010/diff/1/runtime/bin/process.dart#newc...
runtime/bin/process.dart:44: * options other than the executable and the
arguments.
On 2012/09/18 09:34:16, Søren Gjesse wrote:
> Maybe add these two lines on the options argument for start above as well.

It is actually there already. The comment is just truncated in the code review
tool. :)

https://codereview.chromium.org/10938010/diff/1/runtime/bin/process.dart#newc...
runtime/bin/process.dart:52: [ProcessOptions options = null]) {
On 2012/09/18 09:34:16, Søren Gjesse wrote:
> "= null" needed?

Done.

https://codereview.chromium.org/10938010/diff/1/runtime/bin/process.dart#newc...
runtime/bin/process.dart:104: * signal giving, it'll have different meanings.
The default [signal] to
On 2012/09/18 09:34:16, Søren Gjesse wrote:
> No need for documentation of the default value.

Done.

https://codereview.chromium.org/10938010/diff/1/tests/standalone/io/http_head...
File tests/standalone/io/http_headers_test.dart (right):

https://codereview.chromium.org/10938010/diff/1/tests/standalone/io/http_head...
tests/standalone/io/http_headers_test.dart:242: contentType = new
_ContentType("", "");
On 2012/09/18 09:34:16, Søren Gjesse wrote:
> Replace new _ContentType("", "") with new ContentType().

Done.

[William Hesse, 2012-09-21 11:47:39]

I think it might be better to merge Path and _Path, rather than changing to
factory constructors and losing the const constructor.  Not being able to have
const paths seems like a big loss to me (though not as big, now that we allow
non-const initializers for statics).  I don't think there is a big reason to
separate Path and _Path.

[Mads Ager (google), 2012-09-21 11:52:02]

On 2012/09/21 11:47:39, William Hesse wrote:
> I think it might be better to merge Path and _Path, rather than changing to
> factory constructors and losing the const constructor.  Not being able to have
> const paths seems like a big loss to me (though not as big, now that we allow
> non-const initializers for statics).  I don't think there is a big reason to
> separate Path and _Path.

Could you explain to me why you think it is important to have const Paths? I
can't actually think of a situation where it would matter not that statics are
lazily initialized? You can't use equality on paths even if they are const
because two const paths might refer to the same place in the file system. I
might be missing something, but I don't really see why const Paths are useful at
this point.

[William Hesse, 2012-09-21 12:19:48]

I guess the only big disadvantage is that Paths can't be included in a bigger
constant structure now.  I guess it is not likely to be much less efficient to
have lazy final static Paths than to have const Paths.  Having a const
constructor is also a good signal that the class is immutable.



On 2012/09/21 11:52:02, Mads Ager wrote:
> On 2012/09/21 11:47:39, William Hesse wrote:
> > I think it might be better to merge Path and _Path, rather than changing to
> > factory constructors and losing the const constructor.  Not being able to
have
> > const paths seems like a big loss to me (though not as big, now that we
allow
> > non-const initializers for statics).  I don't think there is a big reason to
> > separate Path and _Path.
> 
> Could you explain to me why you think it is important to have const Paths? I
> can't actually think of a situation where it would matter not that statics are
> lazily initialized? You can't use equality on paths even if they are const
> because two const paths might refer to the same place in the file system. I
> might be missing something, but I don't really see why const Paths are useful
at
> this point.

[William Hesse, 2012-09-21 12:22:15]

Also, individual paths constructed inline in functions and loops are now a new
object each time the constructor is hit, rather than reusing the same const
object.  That is a big use case for const lists - we often want const [], rather
than just [].


On 2012/09/21 12:19:48, William Hesse wrote:
> I guess the only big disadvantage is that Paths can't be included in a bigger
> constant structure now.  I guess it is not likely to be much less efficient to
> have lazy final static Paths than to have const Paths.  Having a const
> constructor is also a good signal that the class is immutable.
> 
> 
> 
> On 2012/09/21 11:52:02, Mads Ager wrote:
> > On 2012/09/21 11:47:39, William Hesse wrote:
> > > I think it might be better to merge Path and _Path, rather than changing
to
> > > factory constructors and losing the const constructor.  Not being able to
> have
> > > const paths seems like a big loss to me (though not as big, now that we
> allow
> > > non-const initializers for statics).  I don't think there is a big reason
to
> > > separate Path and _Path.
> > 
> > Could you explain to me why you think it is important to have const Paths? I
> > can't actually think of a situation where it would matter not that statics
are
> > lazily initialized? You can't use equality on paths even if they are const
> > because two const paths might refer to the same place in the file system. I
> > might be missing something, but I don't really see why const Paths are
useful
> at
> > this point.