Add StackTrace.current getter.

sdk/lib/core/stacktrace.dart

 // Copyright (c) 2013, 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.
 
 part of dart.core;
 
 /**
  * An interface implemented by all stack trace objects.
  *
  * A [StackTrace] is intended to convey information to the user about the call
@@ skipping 13 matching lines @@
    *
    * The `stackTraceString` can be a string returned by some other
    * stack trace, or it can be any string at all.
    * If the string doesn't look like a stack trace, code that interprets
    * stack traces is likely to fail, so fake stack traces should be used
    * with care.
    */
   factory StackTrace.fromString(String stackTraceString) = _StringStackTrace;
 
   /**
+   * Returns a representation of the current stack trace.
+   *
+   * This is similar to what can be achieved by doing:
+   *
+   *     try { throw 0; } catch (_, stack) { return stack; }

[kevmoo, 2015/11/17 18:51:44]

Please use
```dart
try { throw 0; } ...
```

syntax for code blocks

[sra1, 2015/11/17 19:13:44]

Shouldn't that be the default for Dart documentation?

[floitsch, 2015/11/17 23:22:32]

There should be no need to specify "dart" as information string.
I also don't see the ``` as a big advantage over few lines of indented code.
Until we allow non-leading "*" it isn't much easier to write either.

In the following example "```" would be easier to edit.

/**
No leading "*"
```
non prefixed code
```
*/

[Lasse Reichstein Nielsen, 2015/11/18 10:11:39]

I fail to see the improvement of

* ```dart
* try ...
* ```

over

*
*     try ...;
*

The latter is *easier* to read as source, and it should generate the same
result.
For larger examples, you may want to avoid the four characters of indentation,
but for a small example like this, it's not really worth it.

+   *
+   * but the getter tries to get the stack without throwing any object

[floitsch, 2015/11/16 19:30:21]

This won't read nice in a formatted output. Just make it a separate sentence.

"The getter ..."

I would be more assertive: "doesn't" (and treat it as a bug for those that do".

[Lasse Reichstein Nielsen, 2015/11/18 10:11:39]

Done.

+   * if it can be avoided.
+   */
+  external static StackTrace get current;
+
+  /**
    * Returns a [String] representation of the stack trace.
    *
    * The string represents the full stack trace starting from
    * the point where a throw ocurred to the top of the current call sequence.
    *
    * The exact format of the string representation is not final.
    */
   String toString();
 }
 
 class _StringStackTrace implements StackTrace {
   final String _stackTrace;
   _StringStackTrace(this._stackTrace);
   String toString() => _stackTrace;
 }