refactor(zone): add return types & doc

Closes #1073

Author: vicb

lib/core/zone.dart

@@ -88,7 +88,8 @@ class VmTurnZone {
   bool _errorThrownFromOnRun = false;
 
   var _currentlyInTurn = false;
-  _onRunBase(async.Zone self, async.ZoneDelegate delegate, async.Zone zone, fn()) {
+
+  dynamic _onRunBase(async.Zone self, async.ZoneDelegate delegate, async.Zone zone, fn()) {
     _runningInTurn++;
     try {
       if (!_currentlyInTurn) {
@@ -105,28 +106,29 @@ class VmTurnZone {
       if (_runningInTurn == 0) _finishTurn(zone, delegate);
     }
   }
+
   // Called from the parent zone.
-  _onRun(async.Zone self, async.ZoneDelegate delegate, async.Zone zone, fn()) =>
+  dynamic _onRun(async.Zone self, async.ZoneDelegate delegate, async.Zone zone, fn()) =>
       _onRunBase(self, delegate, zone, () => delegate.run(zone, fn));
 
-  _onRunUnary(async.Zone self, async.ZoneDelegate delegate, async.Zone zone,
-              fn(args), args) =>
+  dynamic _onRunUnary(async.Zone self, async.ZoneDelegate delegate, async.Zone zone,
+                      fn(args), args) =>
       _onRunBase(self, delegate, zone, () => delegate.runUnary(zone, fn, args));
 
-  _onScheduleMicrotask(async.Zone self, async.ZoneDelegate delegate,
-                       async.Zone zone, fn()) {
+  void _onScheduleMicrotask(async.Zone self, async.ZoneDelegate delegate, async.Zone zone, fn()) {
     onScheduleMicrotask(() => delegate.run(zone, fn));
     if (_runningInTurn == 0 && !_inFinishTurn)  _finishTurn(zone, delegate);
   }
 
-  _uncaughtError(async.Zone self, async.ZoneDelegate delegate, async.Zone zone,
-                 e, StackTrace s) {
+  void _uncaughtError(async.Zone self, async.ZoneDelegate delegate, async.Zone zone,
+                      e, StackTrace s) {
     if (!_errorThrownFromOnRun) onError(e, s, _longStacktrace);
     _errorThrownFromOnRun = false;
   }
 
   var _inFinishTurn = false;
-  _finishTurn(zone, delegate) {
+
+  void _finishTurn(zone, delegate) {
     if (_inFinishTurn) return;
     _inFinishTurn = true;
     try {
@@ -218,15 +220,27 @@ class VmTurnZone {
 
   /**
    * Runs [body] in the inner zone and returns whatever it returns.
+   *
+   * In a typical app where the inner zone is the Angular zone, this allows one to make use of the
+   * Angular's auto digest mechanism.
+   *
+   *    VmTurnZone zone = <ref to app.zone>;
+   *
+   *    void functionCalledFromJS() {
+   *      zone.run(() {
+   *        // auto-digest will run after this function is called from JS
+   *      })
+   *    }
    */
   dynamic run(body()) => _innerZone.run(body);
 
   /**
    * Runs [body] in the outer zone and returns whatever it returns.
-   * In a typical app where the inner zone is the Angular zone, this allows
-   * one to escape Angular's auto-digest mechanism.
    *
-   *     myFunction(VmTurnZone zone, Element element) {
+   * In a typical app where the inner zone is the Angular zone, this allows one to escape Angular's
+   * auto-digest mechanism.
+   *
+   *     void myFunction(VmTurnZone zone, Element element) {
    *       element.onClick.listen(() {
    *         // auto-digest will run after element click.
    *       });