Clean and create output directory when generating docs.

utils/dartdoc/dartdoc.dart

 // Copyright (c) 2011, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 /** An awesome documentation generator. */
 #library('dartdoc');
 
 #import('../../frog/lang.dart');
+#import('../../frog/file_system.dart');
 #import('../../frog/file_system_node.dart');
 
 #source('classify.dart');
 
 /** Path to corePath library. */
 final corePath = 'lib';
 
 /** Path to generate html files into. */
 final outdir = 'docs';
 
 /** Special comment position used to store the library-level doc comment. */
 final _libraryDoc = -1;
 
 /** The file currently being written to. */
 StringBuffer _file;
 
 /**
  * The cached lookup-table to associate doc comments with spans. The outer map
  * is from filenames to doc comments in that file. The inner map maps from the
  * token positions to doc comments. Each position is the starting offset of the
  * next non-comment token *following* the doc comment. For example, the position
  * for this comment would be the position of the "Map" token below.
  */
 Map<String, Map<int, String>> _comments;
 
 int _totalLibraries = 0;
 int _totalTypes = 0;
 int _totalMembers = 0;
 
+FileSystem files;
+
 /**
  * Run this from the frog/samples directory.  Before running, you need
  * to create a docs dir with 'mkdir docs' - since Dart currently doesn't
  * support creating new directories.
  */
 void main() {
   // The entrypoint of the library to generate docs for.
   final libPath = process.argv[2];
 
-  // TODO(rnystrom): Get options and homedir like frog.dart does.
-  final files = new NodeFileSystem();
+  files = new NodeFileSystem();
   parseOptions('../../frog', [] /* args */, files);
 
   final elapsed = time(() {
+    _comments = <String, Map<int, String>>{};
+
     initializeWorld(files);
 
     world.processScript(libPath);
     world.resolveAll();
 
-    _comments = <String, Map<int, String>>{};
+    // Clean the output directory.
+    if (files.fileExists(outdir)) {
+      files.removeDirectory(outdir, recursive: true);
+    }
+    files.createDirectory(outdir, recursive: true);
 
+    // Copy over the static files.
+    for (final file in ['interact.js', 'styles.css']) {
+      copyStatic(file);
+    }
+
+    // Generate the docs.
     for (var library in world.libraries.getValues()) {
       docLibrary(library);
     }
 
     docIndex(world.libraries.getValues());
   });
 
   print('Documented $_totalLibraries libraries, $_totalTypes types, and ' +
         '$_totalMembers members in ${elapsed}msec.');
 }
 
+/** Copies the static file at 'static/file' to the output directory. */
+copyStatic(String file) {
+  var contents = files.readAll(joinPaths('static', file));

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

why not use final for this and other local vars that are final?

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

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:

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

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.
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.

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

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. :) 

+  files.writeString(joinPaths(outdir, file), contents);
+}
+
 num time(callback()) {
   // Unlike world.withTiming, returns the elapsed time.
   final watch = new Stopwatch();
   watch.start();
   callback();
   watch.stop();
   return watch.elapsedInMs();
 }
 
 startFile() {
@@ skipping 462 matching lines @@
     if (line.endsWith('*/')) line = line.substring(0, line.length-2);
     line = line.trim();
     while (line.startsWith('*')) line = line.substring(1, line.length);
     line = line.trim();
     buf.add(line);
     buf.add(' ');
   }
 
   return buf.toString();
 }