Clean and create output directory when generating docs.

Clean and create output directory when generating docs.

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

[Bob Nystrom, 2011-11-16 00:55:44]

Hacked some basic directory functionality for node so that dartdoc can create
the output directory it needs.

[Jacob, 2011-11-16 19:59:30]

http://codereview.chromium.org/8572044/diff/2001/frog/file_system_dom.dart
File frog/file_system_dom.dart (right):

http://codereview.chromium.org/8572044/diff/2001/frog/file_system_dom.dart#ne...
frog/file_system_dom.dart:73: throw 'createDirectory() is not implemented by
DomFileSystem yet.';
perhaps add a TODO for each of these methods?
Also, no need to include DomFileSystem in the error as that's obvious for the
callstack if someone cares.  Same for the method name itself.

http://codereview.chromium.org/8572044/diff/2001/frog/file_system_node.dart
File frog/file_system_node.dart (right):

http://codereview.chromium.org/8572044/diff/2001/frog/file_system_node.dart#n...
frog/file_system_node.dart:31: var parts = path.split('/');
var --> final

http://codereview.chromium.org/8572044/diff/2001/frog/file_system_node.dart#n...
frog/file_system_node.dart:34: for (part = 0; part < parts.length; part++) {
for (part in parts)

parts[part] --> part

http://codereview.chromium.org/8572044/diff/2001/frog/file_system_vm.dart
File frog/file_system_vm.dart (right):

http://codereview.chromium.org/8572044/diff/2001/frog/file_system_vm.dart#new...
frog/file_system_vm.dart:32: throw 'createDirectory() is not implemented by
VMFileSystem yet.';
same comment as other file

http://codereview.chromium.org/8572044/diff/2001/frog/lib/node/node.dart
File frog/lib/node/node.dart (right):

http://codereview.chromium.org/8572044/diff/2001/frog/lib/node/node.dart#newc...
frog/lib/node/node.dart:102: bool isFile() native;
should these be

bool get file() native;
bool get blockDevice() native;
...
?

http://codereview.chromium.org/8572044/diff/2001/utils/dartdoc/dartdoc.dart
File utils/dartdoc/dartdoc.dart (right):

http://codereview.chromium.org/8572044/diff/2001/utils/dartdoc/dartdoc.dart#n...
utils/dartdoc/dartdoc.dart:86: var contents = files.readAll(joinPaths('static',
file));
why not use final for this and other local vars that are final?

http://codereview.chromium.org/8572044/diff/2001/utils/dartdoc/static/styles.css
File utils/dartdoc/static/styles.css (left):

http://codereview.chromium.org/8572044/diff/2001/utils/dartdoc/static/styles....
utils/dartdoc/static/styles.css:34: sans-serif;
tweak the CSS so you only have to specify the font face list once so it is
easier to change

http://codereview.chromium.org/8572044/diff/2001/utils/dartdoc/static/styles.css
File utils/dartdoc/static/styles.css (right):

http://codereview.chromium.org/8572044/diff/2001/utils/dartdoc/static/styles....
utils/dartdoc/static/styles.css:153: pre.source .c { color: hsl(220,  20%, 65%);
} /* Comment */
drive by comments:
us #rgb or #rrggbb colors instead of hsl
While HSL is cool and can express specifying shades from a single color scheme
more easily when using regular CSS, fewer people understand it than rgb  and it
generates longer CSS (assuming your preprocessor doesn't convert to #rgb

http://codereview.chromium.org/8572044/diff/2001/utils/dartdoc/static/styles....
utils/dartdoc/static/styles.css:177: background: -webkit-linear-gradient(top,
#eee 0, #fff 10%, #fff 90%, #eee 100%);
add gradient definitions for moz, ie, and opera as well
there are plenty of convenience tools on the web to help you do this.

[jimhug, 2011-11-17 16:59:44]

lgtm

Assuming that you'll fix Jacob's issue.  You also need to ensure that you've
built frogsh in the same way as presubmit.py.  I believe that the version you
have here was built without --enable_type_checks which makes the code shockingly
different.

http://codereview.chromium.org/8572044/diff/2001/frog/lib/node/node.dart
File frog/lib/node/node.dart (right):

http://codereview.chromium.org/8572044/diff/2001/frog/lib/node/node.dart#newc...
frog/lib/node/node.dart:102: bool isFile() native;
This is a tough interop case and I'm unsure at which layer to make things more
dart-like.  For now, I think that we should stick with a direct clone of the
node apis here whenever possible and worry about the cleaner dart design when we
have an official shared complete file i/o library in dart.

On 2011/11/16 19:59:30, Jacob wrote:
> should these be
> 
> bool get file() native;
> bool get blockDevice() native;
> ...
> ?

http://codereview.chromium.org/8572044/diff/2001/utils/dartdoc/dartdoc.dart
File utils/dartdoc/dartdoc.dart (right):

http://codereview.chromium.org/8572044/diff/2001/utils/dartdoc/dartdoc.dart#n...
utils/dartdoc/dartdoc.dart:86: var contents = files.readAll(joinPaths('static',
file));
This is a good topic.  I've found myself not doing this when I initially write
code as I'm not sure if it will be final or not.  When I go back over things I
will sometimes add final - particularly when I think it communicates something
important.  I'm not at all sure what the right answer is here - but for now I'll
say this should match the dart style guide - and if the style guide is "wrong"
we should fix it first there.

On 2011/11/16 19:59:30, Jacob wrote:
> why not use final for this and other local vars that are final?

http://codereview.chromium.org/8572044/diff/2001/utils/dartdoc/static/styles.css
File utils/dartdoc/static/styles.css (left):

http://codereview.chromium.org/8572044/diff/2001/utils/dartdoc/static/styles....
utils/dartdoc/static/styles.css:34: sans-serif;
+1!!  Of course, what I'd really like is "use a constant in the css to specify
the font list once without having to change your structure at all.  However,
we've got a little time to wait before that is an option <smile>.
On 2011/11/16 19:59:30, Jacob wrote:
> tweak the CSS so you only have to specify the font face list once so it is
> easier to change

http://codereview.chromium.org/8572044/diff/2001/utils/dartdoc/static/styles.css
File utils/dartdoc/static/styles.css (right):

http://codereview.chromium.org/8572044/diff/2001/utils/dartdoc/static/styles....
utils/dartdoc/static/styles.css:153: pre.source .c { color: hsl(220,  20%, 65%);
} /* Comment */
Hmm...  I really liked the hsl colors here when I was hacking on these colors in
the editor code.  I found the ability to tweak the saturation and luminence
really handy.  I'd like to see us continue to use hsl when appropriate - unless
I'm missing something critical.

On 2011/11/16 19:59:30, Jacob wrote:
> drive by comments:
> us #rgb or #rrggbb colors instead of hsl
> While HSL is cool and can express specifying shades from a single color scheme
> more easily when using regular CSS, fewer people understand it than rgb  and
it
> generates longer CSS (assuming your preprocessor doesn't convert to #rgb

http://codereview.chromium.org/8572044/diff/2001/utils/dartdoc/static/styles....
utils/dartdoc/static/styles.css:177: background: -webkit-linear-gradient(top,
#eee 0, #fff 10%, #fff 90%, #eee 100%);
Or...  wait a couple of weeks for Terry's tool to do this automatically for you.
 Unfortunately, given the doc team's desire to use this ASAP, I'd agree with
Jacob that you should fix this for now so we don't send the wrong message with
our docs.

On 2011/11/16 19:59:30, Jacob wrote:
> add gradient definitions for moz, ie, and opera as well
> there are plenty of convenience tools on the web to help you do this.

[jacob314, 2011-11-17 19:06:16]

http://codereview.chromium.org/8572044/diff/2001/frog/lib/node/node.dart
File frog/lib/node/node.dart (right):

http://codereview.chromium.org/8572044/diff/2001/frog/lib/node/node.dart#newc...
frog/lib/node/node.dart:102: bool isFile() native;
I agree that just reusing the node names and at most adding a TODO is the right
call.

On 2011/11/17 16:59:44, jimhug wrote:
> This is a tough interop case and I'm unsure at which layer to make things more
> dart-like.  For now, I think that we should stick with a direct clone of the
> node apis here whenever possible and worry about the cleaner dart design when
we
> have an official shared complete file i/o library in dart.
> 
> On 2011/11/16 19:59:30, Jacob wrote:
> > should these be
> > 
> > bool get file() native;
> > bool get blockDevice() native;
> > ...
> > ?
>

[Bob Nystrom, 2011-11-17 20:44:21]

Made a bunch of stuff final. Also regenerated frogsh with latest code and with
enable_type_checks. I updated the README for frog to include that.

http://codereview.chromium.org/8572044/diff/2001/frog/file_system_dom.dart
File frog/file_system_dom.dart (right):

http://codereview.chromium.org/8572044/diff/2001/frog/file_system_dom.dart#ne...
frog/file_system_dom.dart:73: throw 'createDirectory() is not implemented by
DomFileSystem yet.';
On 2011/11/16 19:59:30, Jacob wrote:
> perhaps add a TODO for each of these methods?
> Also, no need to include DomFileSystem in the error as that's obvious for the
> callstack if someone cares.  Same for the method name itself.

Done.

http://codereview.chromium.org/8572044/diff/2001/frog/file_system_node.dart
File frog/file_system_node.dart (right):

http://codereview.chromium.org/8572044/diff/2001/frog/file_system_node.dart#n...
frog/file_system_node.dart:31: var parts = path.split('/');
On 2011/11/16 19:59:30, Jacob wrote:
> var --> final

Done.

http://codereview.chromium.org/8572044/diff/2001/frog/file_system_node.dart#n...
frog/file_system_node.dart:34: for (part = 0; part < parts.length; part++) {
On 2011/11/16 19:59:30, Jacob wrote:
> for (part in parts)
> 
> parts[part] --> part

I'm using that same `part` index below to continue iterating. I could
conceivably use the Iterator object directly, but that seems like more trouble
than it's worth.

http://codereview.chromium.org/8572044/diff/2001/frog/file_system_vm.dart
File frog/file_system_vm.dart (right):

http://codereview.chromium.org/8572044/diff/2001/frog/file_system_vm.dart#new...
frog/file_system_vm.dart:32: throw 'createDirectory() is not implemented by
VMFileSystem yet.';
On 2011/11/16 19:59:30, Jacob wrote:
> same comment as other file 

Done.

http://codereview.chromium.org/8572044/diff/2001/frog/lib/node/node.dart
File frog/lib/node/node.dart (right):

http://codereview.chromium.org/8572044/diff/2001/frog/lib/node/node.dart#newc...
frog/lib/node/node.dart:102: bool isFile() native;
On 2011/11/17 16:59:44, jimhug wrote:
> This is a tough interop case and I'm unsure at which layer to make things more
> dart-like.  For now, I think that we should stick with a direct clone of the
> node apis here whenever possible and worry about the cleaner dart design when
we
> have an official shared complete file i/o library in dart.
> 
> On 2011/11/16 19:59:30, Jacob wrote:
> > should these be
> > 
> > bool get file() native;
> > bool get blockDevice() native;
> > ...
> > ?
> 

What Jim said. I was under the impression that this layer had to match node's
API exactly since it's using native here. NodeFileSystem then consumes this and
provides a Dartier API.

http://codereview.chromium.org/8572044/diff/2001/utils/dartdoc/dartdoc.dart
File utils/dartdoc/dartdoc.dart (right):

http://codereview.chromium.org/8572044/diff/2001/utils/dartdoc/dartdoc.dart#n...
utils/dartdoc/dartdoc.dart:86: var contents = files.readAll(joinPaths('static',
file));
On 2011/11/17 16:59:44, jimhug wrote:
> This is a good topic.  I've found myself not doing this when I initially write
> code as I'm not sure if it will be final or not.

I do the same thing. Lately, my habit has been to just use "var" for all locals
and not worry too much about it. That being said, when I later read code, I do
find "final" helpful so I don't mind going back and tightening things up.

>  When I go back over things I
> will sometimes add final - particularly when I think it communicates something
> important.  I'm not at all sure what the right answer is here - but for now
I'll
> say this should match the dart style guide - and if the style guide is "wrong"
> we should fix it first there.

I AM the style guide!!! ;)

Actually, it's silent on this since I don't think we've settled on any habit
here yet. I like Jacob's suggestion, though. I'll change these.

Going forward, I think I might try using "final" for everything at first and
then only switching to "var" once I know I need to re-assign.

http://codereview.chromium.org/8572044/diff/2001/utils/dartdoc/static/styles.css
File utils/dartdoc/static/styles.css (left):

http://codereview.chromium.org/8572044/diff/2001/utils/dartdoc/static/styles....
utils/dartdoc/static/styles.css:34: sans-serif;
On 2011/11/17 16:59:44, jimhug wrote:
> +1!!  Of course, what I'd really like is "use a constant in the css to specify
> the font list once without having to change your structure at all.  However,
> we've got a little time to wait before that is an option <smile>.
> On 2011/11/16 19:59:30, Jacob wrote:
> > tweak the CSS so you only have to specify the font face list once so it is
> > easier to change
> 

My (unstated) plan was to do this CSS file the dumb/redundant way now and then
later clean it up using Terry's preprocessor once that's available. I didn't
want to rearrange the styles too much to get around the lack of variables now
since I hope to have them soon.

http://codereview.chromium.org/8572044/diff/2001/utils/dartdoc/static/styles.css
File utils/dartdoc/static/styles.css (right):

http://codereview.chromium.org/8572044/diff/2001/utils/dartdoc/static/styles....
utils/dartdoc/static/styles.css:153: pre.source .c { color: hsl(220,  20%, 65%);
} /* Comment */
On 2011/11/17 16:59:44, jimhug wrote:
> Hmm...  I really liked the hsl colors here when I was hacking on these colors
in
> the editor code.  I found the ability to tweak the saturation and luminence
> really handy.  I'd like to see us continue to use hsl when appropriate -
unless
> I'm missing something critical.
> 
> On 2011/11/16 19:59:30, Jacob wrote:
> > drive by comments:
> > us #rgb or #rrggbb colors instead of hsl
> > While HSL is cool and can express specifying shades from a single color
scheme
> > more easily when using regular CSS, fewer people understand it than rgb  and
> it
> > generates longer CSS (assuming your preprocessor doesn't convert to #rgb
> 

I'm familiar with both but I find hsl much easier to reason about. I spend a lot
of time tweaking colors and rgb is almost unusable for that.

My intent here is that eventually Terry's mojo will bake these down to rgb for
me later at some point.

http://codereview.chromium.org/8572044/diff/2001/utils/dartdoc/static/styles....
utils/dartdoc/static/styles.css:177: background: -webkit-linear-gradient(top,
#eee 0, #fff 10%, #fff 90%, #eee 100%);
On 2011/11/17 16:59:44, jimhug wrote:
> Or...  wait a couple of weeks for Terry's tool to do this automatically for
you.

What Jim said! :)

>  Unfortunately, given the doc team's desire to use this ASAP, I'd agree with
> Jacob that you should fix this for now so we don't send the wrong message with
> our docs.
> 
> On 2011/11/16 19:59:30, Jacob wrote:
> > add gradient definitions for moz, ie, and opera as well
> > there are plenty of convenience tools on the web to help you do this.
> 

These styles are only for debugging and won't actually be seen by users (unless
they actually look at the CSS and we don't minify it...). Note that these are
all commented out here.

[Jacob, 2011-11-17 20:54:08]

LGTM

http://codereview.chromium.org/8572044/diff/2001/utils/dartdoc/dartdoc.dart
File utils/dartdoc/dartdoc.dart (right):

http://codereview.chromium.org/8572044/diff/2001/utils/dartdoc/dartdoc.dart#n...
utils/dartdoc/dartdoc.dart:86: var contents = files.readAll(joinPaths('static',
file));
On 2011/11/17 20:44:21, Bob Nystrom wrote:
> On 2011/11/17 16:59:44, jimhug wrote:
> > This is a good topic.  I've found myself not doing this when I initially
write
> > code as I'm not sure if it will be final or not.
> 
> I do the same thing. Lately, my habit has been to just use "var" for all
locals
> and not worry too much about it. That being said, when I later read code, I do
> find "final" helpful so I don't mind going back and tightening things up.
> 
> >  When I go back over things I
> > will sometimes add final - particularly when I think it communicates
something
> > important.  I'm not at all sure what the right answer is here - but for now
> I'll
> > say this should match the dart style guide - and if the style guide is
"wrong"
> > we should fix it first there.
> 
> I AM the style guide!!! ;)
> 
> Actually, it's silent on this since I don't think we've settled on any habit
> here yet. I like Jacob's suggestion, though. I'll change these.
> 
> Going forward, I think I might try using "final" for everything at first and
> then only switching to "var" once I know I need to re-assign.

using final for everything at first has worked well for me. there are few cases
where I end up having to go back and switch a final to a var or an actual type
and in those cases it often is a sign i could have structured the code a better
way.  but perhaps I just write boring code. :)

[Bob Nystrom, 2011-11-17 20:58:57]

On 2011/11/17 20:54:08, Jacob wrote:

> using final for everything at first has worked well for me. there are few
cases
> where I end up having to go back and switch a final to a var or an actual type
> and in those cases it often is a sign i could have structured the code a
better
> way.  but perhaps I just write boring code. :)

I like this too. Boring code is maintainable code!