Two edits based on feedback from whesse:

include/dart_api.h

 // Copyright (c) 2012, 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.
 
 #ifndef INCLUDE_DART_API_H_
 #define INCLUDE_DART_API_H_
 
 /** \mainpage Dart Embedding API Reference
  *
  * Dart is a class-based programming language for creating structured
@@ skipping 265 matching lines @@
 DART_EXPORT Dart_Handle Dart_NewUnhandledExceptionError(Dart_Handle exception);
 
 // Deprecated.
 // TODO(turnidge): Remove all uses and delete.
 DART_EXPORT Dart_Handle Dart_Error(const char* format, ...);
 
 /**
  * Propagates an error.
  *
  * If the provided handle is an unhandled exception error, this
- * function will cause the unhandled exception to be rethrown.
+ * function will cause the unhandled exception to be rethrown.  This
+ * will proceeed in the standard way, walking up Dart frames until an
+ * appropriate 'catch' block is found, executing 'finally' blocks,
+ * etc.
  *
  * If the error is not an unhandled exception error, we will unwind
- * the stack to the next C frame.  Any intervening Dart frames will
- * be discarded.
+ * the stack to the next C frame.  Intervening Dart frames will be
+ * discarded; specifically, 'finally' blocks will not execute.  This
+ * is the standard way that compilation errors (and the like) are
+ * handled by the Dart runtime.
  *
  * In either case, when an error is propagated any current scopes
  * created by Dart_EnterScope will be exited.
  *
  * See the additonal discussion under "Propagating Errors" at the
  * beginning of this file.
  *
  * \param An error handle (See Dart_IsError)
  *
  * \return On success, this function does not return.  On failure, an
@@ skipping 2044 matching lines @@
                                                     int index,
                                                     intptr_t value);
 
 // --- Exceptions ----
 // TODO(turnidge): Remove these functions from the api and replace all
 // uses with Dart_NewUnhandledExceptionError.
 
 /**
  * Throws an exception.
  *
- * Throws an exception, unwinding all dart frames on the stack. If
- * successful, this function does not return. Note that this means
+ * This function causes a Dart language exception to be thrown. This
+ * will proceeed in the standard way, walking up Dart frames until an
+ * appropriate 'catch' block is found, executing 'finally' blocks,
+ * etc.
+ *
+ * If successful, this function does not return. Note that this means
  * that the destructors of any stack-allocated C++ objects will not be
  * called. If there are no Dart frames on the stack, an error occurs.
  *
  * \return An error handle if the exception was not thrown.
  *   Otherwise the function does not return.
  */
 DART_EXPORT Dart_Handle Dart_ThrowException(Dart_Handle exception);
 
 /**
  * Rethrows an exception.
@@ skipping 239 matching lines @@
 
 typedef void (*Dart_FileWriterFunction)(const char* buffer, int64_t num_bytes);
 
 // Support for generating symbol maps for use by the Linux perf tool.
 DART_EXPORT void Dart_InitPerfEventsSupport(Dart_FileWriterFunction function);
 
 // Support for generating flow graph compiler debugging output into a file.
 DART_EXPORT void Dart_InitFlowGraphPrinting(Dart_FileWriterFunction function);
 
 #endif  // INCLUDE_DART_API_H_