Merge branch 'master' of github.com:dart-lang/dartdoc into 0.15.0-release

Author: jcollins-g

analysis_options.yaml

@@ -2,6 +2,7 @@ analyzer:
   strong-mode: true
   language:
     enableGenericMethods: true
+    enableSuperMixins: true
   exclude:
     - 'doc/**'
     - 'lib/templates/*.html'

lib/src/html/html_generator.dart

@@ -7,9 +7,12 @@ library dartdoc.html_generator;
 import 'dart:async' show Future, StreamController, Stream;
 import 'dart:io' show File;
 
+import 'package:path/path.dart' as p;
+
 import '../generator.dart';
 import '../model.dart';
 import 'html_generator_instance.dart';
+import 'template_data.dart';
 import 'templates.dart';
 
 typedef String Renderer(String input);
@@ -44,7 +47,7 @@ class HtmlGenerator extends Generator {
   Stream<File> get onFileCreated => _onFileCreated.stream;
 
   @override
-  Set<String> get writtenFiles => _instance.writtenFiles;
+  final Set<String> writtenFiles = new Set<String>();
 
   static Future<HtmlGenerator> create(
       {HtmlGeneratorOptions options,
@@ -66,22 +69,61 @@ class HtmlGenerator extends Generator {
 
   /// Actually write out the documentation for [package].
   /// Stores the HtmlGeneratorInstance so we can access it in [writtenFiles].
-  Future generate(Package package, String outputDirectoryPath) {
+  Future generate(Package package, String outputDirectoryPath) async {
     assert(_instance == null);
-    _instance = new HtmlGeneratorInstance(
-        _options, _templates, package, outputDirectoryPath, _onFileCreated);
-    return _instance.generate();
+
+    var enabled = true;
+    void write(String filePath, Object content, {bool allowOverwrite}) {
+      allowOverwrite ??= false;
+      if (!enabled) {
+        throw new StateError('`write` was called after `generate` completed.');
+      }
+      // If you see this assert, we're probably being called to build non-canonical
+      // docs somehow.  Check data.self.isCanonical and callers for bugs.
+      assert(allowOverwrite || !writtenFiles.contains(filePath));
+
+      var file = new File(p.join(outputDirectoryPath, filePath));
+      var parent = file.parent;
+      if (!parent.existsSync()) {
+        parent.createSync(recursive: true);
+      }
+
+      if (content is String) {
+        file.writeAsStringSync(content);
+      } else if (content is List<int>) {
+        file.writeAsBytesSync(content);
+      } else {
+        throw new ArgumentError.value(
+            content, 'content', '`content` must be `String` or `List<int>`.');
+      }
+      _onFileCreated.add(file);
+      writtenFiles.add(filePath);
+    }
+
+    try {
+      _instance =
+          new HtmlGeneratorInstance(_options, _templates, package, write);
+      await _instance.generate();
+    } finally {
+      enabled = false;
+    }
   }
 }
 
-class HtmlGeneratorOptions {
+class HtmlGeneratorOptions implements HtmlOptions {
   final String url;
-  final String relCanonicalPrefix;
   final String faviconPath;
-  final String toolVersion;
-  final bool useCategories;
   final bool prettyIndexJson;
 
+  @override
+  final bool useCategories;
+
+  @override
+  final String relCanonicalPrefix;
+
+  @override
+  final String toolVersion;
+
   HtmlGeneratorOptions(
       {this.url,
       this.relCanonicalPrefix,

lib/src/html/html_generator_instance.dart

@@ -2,9 +2,9 @@
 // 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.
 
-import 'dart:async' show Future, StreamController;
+import 'dart:async' show Future;
 import 'dart:convert' show JsonEncoder;
-import 'dart:io' show Directory, File;
+import 'dart:io' show File;
 
 import 'package:collection/collection.dart' show compareNatural;
 import 'package:dartdoc/src/model_utils.dart';
@@ -19,29 +19,17 @@ import 'resources.g.dart' as resources;
 import 'template_data.dart';
 import 'templates.dart';
 
-class HtmlGeneratorInstance implements HtmlOptions {
+typedef void FileWriter(String path, Object content, {bool allowOverwrite});
+
+class HtmlGeneratorInstance {
   final HtmlGeneratorOptions _options;
   final Templates _templates;
   final Package _package;
-  final String _outputDirectoryPath;
   final List<ModelElement> _documentedElements = <ModelElement>[];
-  final StreamController<File> _onFileCreated;
-
-  @override
-  String get relCanonicalPrefix => _options.relCanonicalPrefix;
-
-  @override
-  String get toolVersion => _options.toolVersion;
-
-  String get _faviconPath => _options.faviconPath;
-  bool get _useCategories => _options.useCategories;
+  final FileWriter _writer;
 
-  // Protect against bugs in canonicalization by tracking what files we
-  // write.
-  final Set<String> writtenFiles = new Set<String>();
-
-  HtmlGeneratorInstance(this._options, this._templates, this._package,
-      this._outputDirectoryPath, this._onFileCreated);
+  HtmlGeneratorInstance(
+      this._options, this._templates, this._package, this._writer);
 
   Future generate() async {
     if (_package != null) {
@@ -50,13 +38,11 @@ class HtmlGeneratorInstance implements HtmlOptions {
     }
 
     await _copyResources();
-    if (_faviconPath != null) {
-      var bytes = new File(_faviconPath).readAsBytesSync();
+    if (_options.faviconPath != null) {
+      var bytes = new File(_options.faviconPath).readAsBytesSync();
       // Allow overwrite of favicon.
-      String filename =
-          path.join(_outputDirectoryPath, 'static-assets', 'favicon.png');
-      writtenFiles.remove(filename);
-      _writeFile(filename, bytes);
+      _writer(path.join('static-assets', 'favicon.png'), bytes,
+          allowOverwrite: true);
     }
   }
 
@@ -95,7 +81,7 @@ class HtmlGeneratorInstance implements HtmlOptions {
     });
 
     String json = encoder.convert(indexItems);
-    _writeFile(path.join(_outputDirectoryPath, 'index.json'), '${json}\n');
+    _writer(path.join('index.json'), '${json}\n');
   }
 
   void _generateDocs() {
@@ -178,7 +164,7 @@ class HtmlGeneratorInstance implements HtmlOptions {
   }
 
   void generatePackage() {
-    TemplateData data = new PackageTemplateData(this, _package, _useCategories);
+    TemplateData data = new PackageTemplateData(_options, _package);
     logInfo('documenting ${_package.name}');
 
     _build('index.html', _templates.indexTemplate, data);
@@ -190,35 +176,35 @@ class HtmlGeneratorInstance implements HtmlOptions {
     if (!lib.isAnonymous && !lib.hasDocumentation) {
       package.warnOnElement(lib, PackageWarning.noLibraryLevelDocs);
     }
-    TemplateData data =
-        new LibraryTemplateData(this, package, lib, _useCategories);
+    TemplateData data = new LibraryTemplateData(_options, package, lib);
 
     _build(path.join(lib.dirName, '${lib.fileName}'),
         _templates.libraryTemplate, data);
   }
 
   void generateClass(Package package, Library lib, Class clazz) {
-    TemplateData data = new ClassTemplateData(this, package, lib, clazz);
+    TemplateData data = new ClassTemplateData(_options, package, lib, clazz);
     _build(path.joinAll(clazz.href.split('/')), _templates.classTemplate, data);
   }
 
   void generateConstructor(
       Package package, Library lib, Class clazz, Constructor constructor) {
     TemplateData data =
-        new ConstructorTemplateData(this, package, lib, clazz, constructor);
+        new ConstructorTemplateData(_options, package, lib, clazz, constructor);
 
     _build(path.joinAll(constructor.href.split('/')),
         _templates.constructorTemplate, data);
   }
 
   void generateEnum(Package package, Library lib, Enum eNum) {
-    TemplateData data = new EnumTemplateData(this, package, lib, eNum);
+    TemplateData data = new EnumTemplateData(_options, package, lib, eNum);
 
     _build(path.joinAll(eNum.href.split('/')), _templates.enumTemplate, data);
   }
 
   void generateFunction(Package package, Library lib, ModelFunction function) {
-    TemplateData data = new FunctionTemplateData(this, package, lib, function);
+    TemplateData data =
+        new FunctionTemplateData(_options, package, lib, function);
 
     _build(path.joinAll(function.href.split('/')), _templates.functionTemplate,
         data);
@@ -227,7 +213,7 @@ class HtmlGeneratorInstance implements HtmlOptions {
   void generateMethod(
       Package package, Library lib, Class clazz, Method method) {
     TemplateData data =
-        new MethodTemplateData(this, package, lib, clazz, method);
+        new MethodTemplateData(_options, package, lib, clazz, method);
 
     _build(
         path.joinAll(method.href.split('/')), _templates.methodTemplate, data);
@@ -236,7 +222,7 @@ class HtmlGeneratorInstance implements HtmlOptions {
   void generateConstant(
       Package package, Library lib, Class clazz, Field property) {
     TemplateData data =
-        new ConstantTemplateData(this, package, lib, clazz, property);
+        new ConstantTemplateData(_options, package, lib, clazz, property);
 
     _build(path.joinAll(property.href.split('/')), _templates.constantTemplate,
         data);
@@ -245,7 +231,7 @@ class HtmlGeneratorInstance implements HtmlOptions {
   void generateProperty(
       Package package, Library lib, Class clazz, Field property) {
     TemplateData data =
-        new PropertyTemplateData(this, package, lib, clazz, property);
+        new PropertyTemplateData(_options, package, lib, clazz, property);
 
     _build(path.joinAll(property.href.split('/')), _templates.propertyTemplate,
         data);
@@ -254,7 +240,7 @@ class HtmlGeneratorInstance implements HtmlOptions {
   void generateTopLevelProperty(
       Package package, Library lib, TopLevelVariable property) {
     TemplateData data =
-        new TopLevelPropertyTemplateData(this, package, lib, property);
+        new TopLevelPropertyTemplateData(_options, package, lib, property);
 
     _build(path.joinAll(property.href.split('/')),
         _templates.topLevelPropertyTemplate, data);
@@ -263,14 +249,15 @@ class HtmlGeneratorInstance implements HtmlOptions {
   void generateTopLevelConstant(
       Package package, Library lib, TopLevelVariable property) {
     TemplateData data =
-        new TopLevelConstTemplateData(this, package, lib, property);
+        new TopLevelConstTemplateData(_options, package, lib, property);
 
     _build(path.joinAll(property.href.split('/')),
         _templates.topLevelConstantTemplate, data);
   }
 
   void generateTypeDef(Package package, Library lib, Typedef typeDef) {
-    TemplateData data = new TypedefTemplateData(this, package, lib, typeDef);
+    TemplateData data =
+        new TypedefTemplateData(_options, package, lib, typeDef);
 
     _build(path.joinAll(typeDef.href.split('/')), _templates.typeDefTemplate,
         data);
@@ -285,44 +272,16 @@ class HtmlGeneratorInstance implements HtmlOptions {
             'encountered $resourcePath');
       }
       String destFileName = resourcePath.substring(prefix.length);
-      _writeFile(path.join(_outputDirectoryPath, 'static-assets', destFileName),
+      _writer(path.join('static-assets', destFileName),
           await loader.loadAsBytes(resourcePath));
     }
   }
 
   void _build(String filename, TemplateRenderer template, TemplateData data) {
-    String fullName = path.join(_outputDirectoryPath, filename);
-
     String content = template(data,
         assumeNullNonExistingProperty: false, errorOnMissingProperty: true);
 
-    _writeFile(fullName, content);
-    if (data.self is ModelElement) {
-      _documentedElements.add(data.self);
-    }
-  }
-
-  /// [content] must be either [String] or [List<int>].
-  void _writeFile(String filename, Object content) {
-    // If you see this assert, we're probably being called to build non-canonical
-    // docs somehow.  Check data.self.isCanonical and callers for bugs.
-    assert(!writtenFiles.contains(filename));
-
-    File file = new File(filename);
-    Directory parent = file.parent;
-    if (!parent.existsSync()) {
-      parent.createSync(recursive: true);
-    }
-
-    if (content is String) {
-      file.writeAsStringSync(content);
-    } else if (content is List<int>) {
-      file.writeAsBytesSync(content);
-    } else {
-      throw new ArgumentError.value(
-          content, 'content', '`content` must be `String` or `List<int>`.');
-    }
-    _onFileCreated.add(file);
-    writtenFiles.add(filename);
+    _writer(filename, content);
+    if (data.self is ModelElement) _documentedElements.add(data.self);
   }
 }