Document that terse doesn't work with JS traces. (flutter#15)

Closes flutter#14

CHANGELOG.md

@@ -1,3 +1,7 @@
+## 1.6.8
+
+* Add a note to the documentation of `Chain.terse` and `Trace.terse`.
+
 ## 1.6.7
 
 * Fix a bug where `new Frame.caller()` returned the wrong depth of frame on

lib/src/chain.dart

@@ -150,6 +150,13 @@ class Chain implements StackTrace {
   ///
   /// This calls [Trace.terse] on every trace in [traces], and discards any
   /// trace that contain only internal frames.
+  ///
+  /// This won't do anything with a raw JavaScript trace, since there's no way
+  /// to determine which frames come from which Dart libraries. However, the
+  /// [`source_map_stack_trace`][source_map_stack_trace] package can be used to
+  /// convert JavaScript traces into Dart-style traces.
+  ///
+  /// [source_map_stack_trace]: https://pub.dartlang.org/packages/source_map_stack_trace
   Chain get terse => foldFrames((_) => false, terse: true);
 
   /// Returns a new [Chain] based on [this] where multiple stack frames matching

lib/src/trace.dart

@@ -225,6 +225,13 @@ class Trace implements StackTrace {
   /// removed. If the outermost frame of the stack trace is a core library
   /// frame, it's removed entirely.
   ///
+  /// This won't do anything with a raw JavaScript trace, since there's no way
+  /// to determine which frames come from which Dart libraries. However, the
+  /// [`source_map_stack_trace`][source_map_stack_trace] package can be used to
+  /// convert JavaScript traces into Dart-style traces.
+  ///
+  /// [source_map_stack_trace]: https://pub.dartlang.org/packages/source_map_stack_trace
+  ///
   /// For custom folding, see [foldFrames].
   Trace get terse => foldFrames((_) => false, terse: true);
 

pubspec.yaml

@@ -7,7 +7,7 @@ name: stack_trace
 #
 # When the major version is upgraded, you *must* update that version constraint
 # in pub to stay in sync with this.
-version: 1.6.8-dev
+version: 1.6.8
 author: "Dart Team <[email protected]>"
 homepage: https://github.com/dart-lang/stack_trace
 description: >