First pass at build dependency graph for barback.

pkg/barback/lib/transformer.dart

+// Copyright (c) 2013, the Dart project authors.  Please see the AUTHORS file

[nweiz, 2013/06/14 00:57:57]

I don't understand why the classes in this file are separate from barback.dart.

[Bob Nystrom, 2013/06/17 23:35:05]

I thought it might be nice to separate out the public APIs for someone just
using barback versus someone implementing their own transformer. If you're just
using barback, you'll only import barback.dart.

[nweiz, 2013/06/18 23:14:45]

As I mentioned elsewhere, this sort of thing should be done by exporting "src"
files. I'm not sure there's a lot of value in providing this narrow of an
import, though... if barback.dart only adds the name "Barback" to the top-level,
that doesn't seem like something anyone would care about avoiding.

[Bob Nystrom, 2013/06/20 00:23:59]

OK. Done.

+// 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.
+
+library barback.generator;
+
+import 'dart:async';
+import 'dart:io';
+
+import 'package:pathos/path.dart' as pathos;
+
+import 'barback.dart';
+
+/// A [Transformer] represents a processing step that can take in one or more

[nweiz, 2013/06/14 00:57:57]

"processing step" here is confusing; it sounds like a transformer is a node in
the asset graph. It blurs the difference between Transformer, Transform, and
_TransformNode. Maybe "processor" instead?

[Bob Nystrom, 2013/06/17 23:35:05]

Done.

+/// input assets and use them to generate one or more output assets.
+///
+/// Dart2js, a SASS->CSS processor, a CSS spriter, and a tool to concatenate JS
+/// files are all examples of transformers. To define your own transformation

[nweiz, 2013/06/14 00:57:57]

"a tool to concatenate JS files" is a weird example, since it's unlikely to ever
be used by a Dart project.

[Bob Nystrom, 2013/06/17 23:35:05]

Done.

+/// step, you extend (or implement) this class.

[nweiz, 2013/06/14 00:57:57]

"you" -> ""

[Bob Nystrom, 2013/06/17 23:35:05]

Done.

+abstract class Transformer {
+  /// Returns `true` if [input] can be a primary input for this transformer.
+  /// This is used to tell which files this transformer applies to.

[nweiz, 2013/06/14 00:57:57]

Explain what a primary input is.

[Bob Nystrom, 2013/06/17 23:35:05]

Done.

+  Future<bool> isPrimary(AssetId input);
+
+  /// Process this transformer on [transform], which describes the actual

[nweiz, 2013/06/14 00:57:57]

"Process this transformer on [transform]" is very confusing. What does it mean
to process a transformer?

Maybe something like "Run this transformer on the primary input described by
[transform]."

[Bob Nystrom, 2013/06/17 23:35:05]

Done.

+  /// assets being transformed.

[nweiz, 2013/06/14 00:57:57]

I don't think it's accurate to say that a Transform "describes the assets being
transformed". It only includes the primary asset, and otherwise just provides
access to additional inputs.

Also, this documentation should explain how the transformer is supposed to use
Transform (e.g. call [getInput], do stuff, then call [addOutput]).

[Bob Nystrom, 2013/06/17 23:35:05]

Done.

+  Future apply(Transform transform);
+
+  String toString() => runtimeType.toString().replaceAll("Transformer", "");
+}
+
+/// While a [Transformer] represents a *kind* of transformation, this defines
+/// one specific usage of it on a set of files. It is used in [apply()] to

[nweiz, 2013/06/14 00:57:57]

"usage" -> "instance"

"It is used" -> "Transformers use a Transform"

[Bob Nystrom, 2013/06/17 23:35:05]

Reworded.

+/// access the inputs for the transformation and to provide the outputs.
+abstract class Transform {
+  /// Gets the ID of the primary input for this transformation. While a
+  /// transformation can use multiple input assets, one must be a special
+  /// "primary" asset. This will be the "entrypoint" or "main" input file for
+  /// a transformation.
+  ///
+  /// For example, with a dart2js transform, the primary input would be the
+  /// entrypoint Dart file. All of the other Dart files that that imports
+  /// would be other, secondary inputs.

[nweiz, 2013/06/14 00:57:57]

"other," -> ""

[Bob Nystrom, 2013/06/17 23:35:05]

Done.

+  AssetId get primaryId;
+
+  /// Gets the asset for the primary input.
+  Future<Asset> get primaryInput => getInput(primaryId);
+
+  /// Gets the asset for for an input [id]. If an input with that ID cannot be
+  /// found, throws an [AssetNotFoundException].
+  Future<Asset> getInput(AssetId id);
+
+  /// Stores [output] as the output created by this transformation for asset
+  /// [id]. A transformation can output as many assets as it wants.
+  void addOutput(AssetId id, Asset output);
+}