Deal with unhandled exceptions the same way in all Dart api functions.

runtime/include/dart_api.h

 // Copyright (c) 2011, 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 46 matching lines @@
 /**
  * An object reference managed by the Dart VM garbage collector.
  *
  * Because the garbage collector may move objects, it is unsafe to
  * refer to objects directly. Instead, we refer to objects through
  * handles, which are known to the garbage collector and updated
  * automatically when the object is moved. Handles should be passed
  * by value (except in cases like out-parameters) and should never be
  * allocated on the heap.
  *
- * A handle may either be valid or invalid. Valid handles refer to a
- * object in the Dart VM heap. Note that a valid handle may in some
- * cases refer to null or an unhandled exception. Invalid handles are
- * returned by many Dart api functions when they encounter an error.
- * Invalid handles have an associated error message.
+ * Most functions in the Dart Embedding API return a handle. When a
+ * function completes normally, this will be a valid handle to an
+ * object in the Dart VM heap. This handle may represent the result of
+ * the operation or it may be a special valid handle used merely to
+ * indicate successful completion. Note that a valid handle may in
+ * some cases refer to the null object.
+ *
+ * When a function encounters a problem that prevents it from
+ * completing normally, it returns an error handle (See Dart_IsError).
+ * An error handle has an associated error message that gives more
+ * details about the problem (See Dart_GetError).
+ *
+ * When an unhandled exception occurs, it is returned as a special
+ * kind of error handle (See Dart_IsUnhandledException). This error
+ * handle retains information about the exception and the stack trace
+ * (See Dart_GetException, Dart_GetStacktrace, Dart_RethrowException).
  *
  * Local handles are allocated within the current scope (see
  * Dart_EnterScope) and go away when the current scope exits. Unless
- * otherwise indicated, all functions in the Dart embedding api return
- * local handles.
+ * otherwise indicated, callers should assume that all functions in
+ * the Dart embedding api return local handles.
  *
  * Persistent handles are allocated within the current isolate. They
- * can be used to store objects across scopes. Persistent handles
- * need to be explicitly deallocated when they are no longer needed.
+ * can be used to store objects across scopes. Persistent handles have
+ * the lifetime of the current isolate unless they are explicitly
+ * deallocated (see Dart_DeletePersistentHandle).
  */
 typedef void* Dart_Handle;
 
 /**
- * Is this handle valid?
+ * Is this an error handle?
  *
  * Requires there to be a current isolate.
  */
-DART_EXPORT bool Dart_IsValid(const Dart_Handle& handle);
-
-// Internal routine used for reporting invalid handles.
-DART_EXPORT void _Dart_ReportInvalidHandle(const char* file,
-                                           int line,
-                                           const char* handle_string,
-                                           const char* error);
+DART_EXPORT bool Dart_IsError(const Dart_Handle& handle);
 
 /**
- * Aborts the process if 'handle' is invalid.
- *
- * Provided for convenience.
- */
-#define DART_CHECK_VALID(handle)                                        \
-  if (!Dart_IsValid((handle))) {                                        \
-    _Dart_ReportInvalidHandle(__FILE__, __LINE__,                       \
-                              #handle, Dart_GetError(handle));          \
-  }
-
-/**
- * Gets the error message from an invalid handle.
+ * Gets the error message from an error handle.
  *
  * Requires there to be a current isolate.
  *
  * \return A C string containing an error message if the handle is
- *   invalid. An empty C string ("") if the handle is valid.  This C
+ *   error. An empty C string ("") if the handle is valid. This C
  *   String is scope allocated and is only valid until the next call
  *   to Dart_ExitScope.
 */
 DART_EXPORT const char* Dart_GetError(const Dart_Handle& handle);
 
 /**
- * Produces an invalid handle with the provided error message.
+ * Is this an error handle for an unhandled exception?
+ */
+DART_EXPORT bool Dart_IsUnhandledException(Dart_Handle handle);
+
+/**
+ * Gets the exception Object from an unhandled exception error handle.
+ */
+DART_EXPORT Dart_Handle Dart_GetException(Dart_Handle handle);
+
+/**
+ * Gets the stack trace Object from an unhandled exception error handle.
+ */
+DART_EXPORT Dart_Handle Dart_GetStacktrace(Dart_Handle handle);
+
+/**
+ * Produces an error handle with the provided error message.
  *
  * Requires there to be a current isolate.
  *
  * \param error A C string containing an error message.
  */
 DART_EXPORT Dart_Handle Dart_Error(const char* format, ...);
 
+// Internal routine used for reporting error handles.
+DART_EXPORT void _Dart_ReportErrorHandle(const char* file,
+                                           int line,

[Anton Muhin, 2011/11/09 12:34:03]

nit: you may want to fix indentation: cf. const char* file and int line.

[turnidge, 2011/11/09 19:53:41]

Done.

+                                           const char* handle_string,
+                                           const char* error);
+
+/**
+ * Aborts the process if 'handle' is an error handle.
+ *
+ * Provided for convenience.
+ */
+#define DART_CHECK_VALID(handle)                                        \
+  if (Dart_IsError((handle))) {                                         \
+    _Dart_ReportErrorHandle(__FILE__, __LINE__,                       \
+                              #handle, Dart_GetError(handle));          \
+  }
+
 /**
  * Converts an object to a string.
  *
- * If an exception occurs during the conversion, this is treated as an
- * error.
+ * May generate an unhandled exception error.
  *
- * \return A handle to the converted string if no errors occur during
- * the conversion. If an error does occur, an invalid handle is
- * returned.
+ * \return A handle to the converted string if no error occurs during
+ *   the conversion. If an error does occur, an error handle is
+ *   returned.
  */
 DART_EXPORT Dart_Handle Dart_ToString(Dart_Handle object);
 
 /**
  * Checks if the two objects are the same object
  *
  * The result of the comparison is returned through the 'same'
  * parameter. The return value itself is used to indicate success or
  * failure, not identity.
  *
@@ skipping 89 matching lines @@
 
 /**
  * An isolate is the unit of concurrency in Dart. Each isolate has
  * its own memory and thread of control. No state is shared between
  * isolates. Instead, isolates communicate by message passing.
  *
  * Each thread keeps track of its current isolate, which is the
  * isolate which is ready to execute on the current thread. The
  * current isolate may be NULL, in which case no isolate is ready to
  * execute. Most of the Dart apis require there to be a current
- * isolate in order to function without error.  The current isolate is
+ * isolate in order to function without error. The current isolate is
  * set by any call to Dart_CreateIsolate or Dart_EnterIsolate.
  */
 typedef void* Dart_Isolate;
 
 /**
  * A buffer containing a snapshot of the Dart VM. A snapshot can be
  * used to restore the VM quickly to a saved state and is useful for
  * fast startup.
  */
 typedef void Dart_Snapshot;
@@ skipping 33 matching lines @@
 DART_EXPORT Dart_Isolate Dart_CurrentIsolate();
 
 /**
  * Enters an isolate. After calling this function,
  * the current isolate will be set to the provided isolate.
  *
  * Requires there to be no current isolate.
  */
 DART_EXPORT void Dart_EnterIsolate(Dart_Isolate isolate);
 // TODO(turnidge): Describe what happens if two threads attempt to
-// enter the same isolate simultaneously.  Check for this in the code.
+// enter the same isolate simultaneously. Check for this in the code.
 // Describe whether isolates are allowed to migrate.
 
 /**
  * Exits an isolate. After this call, Dart_CurrentIsolate will
  * return NULL.
  *
  * Requires there to be a current isolate.
  */
 DART_EXPORT void Dart_ExitIsolate();
 // TODO(turnidge): We don't want users of the api to be able to exit a
-// "pure" dart isolate.  Implement and document.
+// "pure" dart isolate. Implement and document.
 
 /**
  * Creates a snapshot of the state of the current isolate.
  */
 DART_EXPORT Dart_Handle Dart_CreateSnapshot(uint8_t** snaphot_buffer,
                                             intptr_t* snapshot_size);
 // TODO(turnidge): Does this include the current script or only libs?
 // is it possible to take a snapshot and load more scripts into it?
 
 // --- Messages and Ports ---
@@ skipping 56 matching lines @@
  */
 DART_EXPORT void Dart_SetMessageCallbacks(
     Dart_PostMessageCallback post_message_callback,
     Dart_ClosePortCallback close_port_callback);
 // TODO(turnidge): Consider moving this to isolate creation so that it
 // is impossible to mess up.
 
 /**
  * Handles a message on the current isolate.
  *
+ * May generate an unhandled exception error.
+ *
  * Note that this function does not free the memory associated with
  * 'dart_message'.
+ *
+ * \return A valid handle if no error occurs during the operation.
  */
-DART_EXPORT void Dart_HandleMessage(Dart_Port dest_port,
-                                    Dart_Port reply_port,
-                                    Dart_Message dart_message);
+DART_EXPORT Dart_Handle Dart_HandleMessage(Dart_Port dest_port,
+                                           Dart_Port reply_port,
+                                           Dart_Message dart_message);
 // TODO(turnidge): Revisit memory management of 'dart_message'.
 
 /**
  * Processes any incoming messages for the current isolate.
  *
  * This function may only be used when the embedder has not provided
  * an alternate message delivery mechanism with
  * Dart_SetMessageCallbacks. It is provided for convenience.
  *
  * This function waits for incoming messages for the current
@@ skipping 71 matching lines @@
  */
 DART_EXPORT bool Dart_IsNull(Dart_Handle object);
 
 /**
  * Checks if the two objects are equal.
  *
  * The result of the comparison is returned through the 'equal'
  * parameter. The return value itself is used to indicate success or
  * failure, not equality.
  *
+ * May generate an unhandled exception error.
+ *
  * \param obj1 An object to be compared.
  * \param obj2 An object to be compared.
  * \param equal Returns the result of the equality comparison.
  *
  * \return A valid handle if no error occurs during the comparison.
  */
 DART_EXPORT Dart_Handle Dart_ObjectEquals(Dart_Handle obj1,
                                           Dart_Handle obj2,
                                           bool* equal);
 
@@ skipping 36 matching lines @@
  * \return A valid handle if no error occurs during the operation.
  */
 DART_EXPORT Dart_Handle Dart_IntegerFitsIntoInt64(Dart_Handle integer,
                                                   bool* fits);
 
 /**
  * Returns an Integer with the provided value.
  *
  * \param value The value of the integer.
  *
- * \return The Integer object if no errors occurs. Otherwise returns
- *   an invalid handle.
+ * \return The Integer object if no error occurs. Otherwise returns
+ *   an error handle.
  */
 DART_EXPORT Dart_Handle Dart_NewInteger(int64_t value);
 
 /**
  * Returns an Integer with the provided value.
  *
  * \param value The value of the integer represented as a C string
  *   containing a hexadecimal number.
  *
- * \return The Integer object if no errors occurs. Otherwise returns
- *   an invalid handle.
+ * \return The Integer object if no error occurs. Otherwise returns
+ *   an error handle.
  */
 DART_EXPORT Dart_Handle Dart_NewIntegerFromHexCString(const char* value);
 
 /**
  * Gets the value of an Integer.
  *
  * The integer must fit into a 64-bit signed integer, otherwise an error occurs.
  *
  * \param integer An Integer.
  * \param value Returns the value of the Integer.
@@ skipping 38 matching lines @@
 /**
  * Is this object a Boolean?
  */
 DART_EXPORT bool Dart_IsBoolean(Dart_Handle object);
 
 /**
  * Returns a Boolean with the provided value.
  *
  * \param value true or false.
  *
- * \return The Boolean object if no errors occurs. Otherwise returns
- *   an invalid handle.
+ * \return The Boolean object if no error occurs. Otherwise returns
+ *   an error handle.
  */
 DART_EXPORT Dart_Handle Dart_NewBoolean(bool value);
 
 /**
  * Gets the value of a Boolean
  *
  * \param bool_object A Boolean
  * \param value Returns the value of the Boolean.
  *
  * \return A valid handle if no error occurs during the operation.
  */
 DART_EXPORT Dart_Handle Dart_BooleanValue(Dart_Handle bool_object, bool* value);
 
 // --- Doubles ---
 
 /**
  * Is this object a Double?
  */
 DART_EXPORT bool Dart_IsDouble(Dart_Handle object);
 
 /**
  * Returns a Double with the provided value.
  *
  * \param value A double.
  *
- * \return The Double object if no errors occurs. Otherwise returns
- *   an invalid handle.
+ * \return The Double object if no error occurs. Otherwise returns
+ *   an error handle.
  */
 DART_EXPORT Dart_Handle Dart_NewDouble(double value);
 
 /**
  * Gets the value of a Double
  *
  * \param bool_object A Double
  * \param value Returns the value of the Double.
  *
  * \return A valid handle if no error occurs during the operation.
@@ skipping 25 matching lines @@
  *
  * \return A valid handle if no error occurs during the operation.
  */
 DART_EXPORT Dart_Handle Dart_StringLength(Dart_Handle str, intptr_t* length);
 
 /**
  * Returns a String built from the provided C string
  *
  * \param value A C String
  *
- * \return The String object if no errors occurs. Otherwise returns
- *   an invalid handle.
+ * \return The String object if no error occurs. Otherwise returns
+ *   an error handle.
  */
 DART_EXPORT Dart_Handle Dart_NewString(const char* str);
 
 /**
  * Returns a String built from an array of 8-bit codepoints.
  *
  * \param value An array of 8-bit codepoints.
  * \param length The length of the codepoints array.
  *
- * \return The String object if no errors occurs. Otherwise returns
- *   an invalid handle.
+ * \return The String object if no error occurs. Otherwise returns
+ *   an error handle.
  */
 DART_EXPORT Dart_Handle Dart_NewString8(const uint8_t* codepoints,
                                         intptr_t length);
 
 /**
  * Returns a String built from an array of 16-bit codepoints.
  *
  * \param value An array of 16-bit codepoints.
  * \param length The length of the codepoints array.
  *
- * \return The String object if no errors occurs. Otherwise returns
- *   an invalid handle.
+ * \return The String object if no error occurs. Otherwise returns
+ *   an error handle.
  */
 DART_EXPORT Dart_Handle Dart_NewString16(const uint16_t* codepoints,
                                          intptr_t length);
 
 /**
  * Returns a String built from an array of 32-bit codepoints.
  *
  * \param value An array of 32-bit codepoints.
  * \param length The length of the codepoints array.
  *
- * \return The String object if no errors occurs. Otherwise returns
- *   an invalid handle.
+ * \return The String object if no error occurs. Otherwise returns
+ *   an error handle.
  */
 DART_EXPORT Dart_Handle Dart_NewString32(const uint32_t* codepoints,
                                          intptr_t length);
 
 /**
  * Gets the codepoints from a String.
  *
  * This function is only valid on strings for which Dart_IsString8 is
  * true. Otherwise an error occurs.
  *
@@ skipping 62 matching lines @@
 /**
  * Is this object a List?
  */
 DART_EXPORT bool Dart_IsList(Dart_Handle object);
 
 /**
  * Returns a List of the desired length.
  *
  * \param length The length of the list.
  *
- * \return The List object if no errors occurs. Otherwise returns
- *   an invalid handle.
+ * \return The List object if no error occurs. Otherwise returns
+ *   an error handle.
  */
 DART_EXPORT Dart_Handle Dart_NewList(intptr_t length);
 
 /**
  * Gets the length of a List.
  *
+ * May generate an unhandled exception error.

[Anton Muhin, 2011/11/09 12:34:03]

I am slightly concerned with tagging API functions with this info: it may be
hard to maintain.  E.g. we recently changed List API to allow it to deal w/
classes implementing List.  The change would be somewhat more difficult if we
committed to not throwing before.

I don't want to say we cannot maintain this information, but maybe we should ask
embedders to be overparanoid and assume any method may throw an exception.  That
doesn't look like a heavy burden: I would expect many people to write one
function to handle error handles anyway.

Up to you though.

[turnidge, 2011/11/09 19:53:41]

I see your point.  We don't want to have our hands tied in the future with
regards to these tags.

I was thinking back to when I was using python's C api to embed python. 
Sometimes the api would fail to say what could happen and I'd end up needing to
go read the source to figure little details out.

Let's see what Ivan's take on it is.  I'm in the middle.

[Ivan Posva, 2011/11/10 18:05:46]

Until we have a better place to stick this kind of documentation we should leave
it here.

[turnidge, 2011/11/10 20:59:13]

Okay.  Leaving as is for now.

+ *
  * \param list A List.
  * \param length Returns the length of the List.
  *
  * \return A valid handle if no error occurs during the operation.
  */
 DART_EXPORT Dart_Handle Dart_ListLength(Dart_Handle list, intptr_t* length);
 
 /**
  * Gets the Object at some index of a List.
  *
  * If the index is out of bounds, an error occurs.
  *
+ * May generate an unhandled exception error.
+ *
  * \param list A List.
  * \param index A valid index into the List.
  *
  * \return The Object in the List at the specified index if no errors
- *   occurs. Otherwise returns an invalid handle.
+ *   occurs. Otherwise returns an error handle.
  */
 DART_EXPORT Dart_Handle Dart_ListGetAt(Dart_Handle list,
                                        intptr_t index);
 
 /**
  * Sets the Object at some index of a List.
  *
  * If the index is out of bounds, an error occurs.
  *
+ * May generate an unhandled exception error.
+ *
  * \param array A List.
  * \param index A valid index into the List.
  * \param value The Object to put in the List.
  *
  * \return A valid handle if no error occurs during the operation.
  */
 DART_EXPORT Dart_Handle Dart_ListSetAt(Dart_Handle list,
                                        intptr_t index,
                                        Dart_Handle value);
 
+/**
+ * May generate an unhandled exception error.
+ */
 DART_EXPORT Dart_Handle Dart_ListGetAsBytes(Dart_Handle list,
                                             intptr_t offset,
                                             uint8_t* native_array,
                                             intptr_t length);
 
+/**
+ * May generate an unhandled exception error.
+ */
 DART_EXPORT Dart_Handle Dart_ListSetAsBytes(Dart_Handle list,
                                             intptr_t offset,
                                             uint8_t* native_array,
                                             intptr_t length);
 
 // --- Closures ---
 
 /**
  * Is this object a Closure?
  */
 DART_EXPORT bool Dart_IsClosure(Dart_Handle object);
 
 /**
  * Invokes a Closure with the given arguments.
  *
+ * May generate an unhandled exception error.
+ *
  * \return If no error occurs during execution, then the result of
- *   invoking the closure is returned. Note that this may be an
- *   uncaught exception (see Dart_ExceptionOccurred) or the null
- *   Object. If an error occurred during execution, then an invalid
- *   handle is returned.
+ *   invoking the closure is returned. If an error occurs during
+ *   execution, then an error handle is returned.
  */
 DART_EXPORT Dart_Handle Dart_InvokeClosure(Dart_Handle closure,
                                            int number_of_arguments,
                                            Dart_Handle* arguments);
 
 // DEPRECATED: The API below is a temporary hack.
 DART_EXPORT int64_t Dart_ClosureSmrck(Dart_Handle object);
 
 // DEPRECATED: The API below is a temporary hack.
 DART_EXPORT void Dart_ClosureSetSmrck(Dart_Handle object, int64_t value);
 
 // --- Methods and Fields ---
 
 /**
  * Invokes a static method with the given arguments.
  *
+ * May generate an unhandled exception error.
+ *
  * \return If no error occurs during execution, then the result of
- *   invoking the closure is returned. Note that this may be an
- *   uncaught exception (see Dart_ExceptionOccurred) or the null
- *   Object. If an error occurred during execution, then an invalid
- *   handle is returned.
+ *   invoking the method is returned. If an error occurs during
+ *   execution, then an error handle is returned.
  */
 DART_EXPORT Dart_Handle Dart_InvokeStatic(Dart_Handle library,
                                           Dart_Handle class_name,
                                           Dart_Handle function_name,
                                           int number_of_arguments,
                                           Dart_Handle* arguments);
 
 /**
  * Invokes an instance method with the given arguments.
  *
+ * May generate an unhandled exception error.
+ *
  * \return If no error occurs during execution, then the result of
- *   invoking the closure is returned. Note that this may be an
- *   uncaught exception (see Dart_ExceptionOccurred) or the null
- *   Object. If an error occurred during execution, then an invalid
- *   handle is returned.
+ *   invoking the method is returned. If an error occurs during
+ *   execution, then an error handle is returned.
  */
 DART_EXPORT Dart_Handle Dart_InvokeDynamic(Dart_Handle receiver,
                                            Dart_Handle function_name,
                                            int number_of_arguments,
                                            Dart_Handle* arguments);
 
 /**
  * Gets the value of a static field.
  *
+ * May generate an unhandled exception error.
+ *
  * \return If no error occurs, then the value of the field is
- *   returned. Otherwise an invalid handle is returned.
+ *   returned. Otherwise an error handle is returned.
  */
 DART_EXPORT Dart_Handle Dart_GetStaticField(Dart_Handle cls, Dart_Handle name);
 
 /**
  * Sets the value of a static field.
  *
+ * May generate an unhandled exception error.
+ *
  * \return A valid handle if no error occurs.
  */
 DART_EXPORT Dart_Handle Dart_SetStaticField(Dart_Handle cls,
                                             Dart_Handle name,
                                             Dart_Handle value);
+
 /**
  * Gets the value of an instance field.
  *
+ * May generate an unhandled exception error.
+ *
  * \return If no error occurs, then the value of the field is
- *   returned. Otherwise an invalid handle is returned.
+ *   returned. Otherwise an error handle is returned.
  */
 DART_EXPORT Dart_Handle Dart_GetInstanceField(Dart_Handle obj,
                                               Dart_Handle name);
 /**
  * Sets the value of an instance field.
  *
+ * May generate an unhandled exception error.
+ *
  * \return A valid handle if no error occurs.
  */
 DART_EXPORT Dart_Handle Dart_SetInstanceField(Dart_Handle obj,
                                               Dart_Handle name,
                                               Dart_Handle value);
 
 /**
  * Creates a native wrapper class.
  *
  * TODO(turnidge): Document.
@@ skipping 15 matching lines @@
  *
  * TODO(turnidge): Document.
  */
 DART_EXPORT Dart_Handle Dart_SetNativeInstanceField(Dart_Handle obj,
                                                     int index,
                                                     intptr_t value);
 
 // --- Exceptions ----
 
 /**
- * Does this handle hold information about an unhandled exception?
- */
-DART_EXPORT bool Dart_ExceptionOccurred(Dart_Handle handle);
-// TODO(turnidge): Consider exposing the name of this thing. Maybe
-// IsUnhandledException, IsUncaughtException, or IsThrownException.
-// It is like a regular exception, but plus a stack trace.
-// TODO(turnidge): Consider subsuming exception results into invalid
-// handles so that only one error check needs to be done after method
-// invocation.
-
-/**
- * Gets the exception Object from an unhandled exception.
- */
-DART_EXPORT Dart_Handle Dart_GetException(Dart_Handle result);
-
-/**
- * Gets the stack trace Object from an unhandled exception.
- */
-DART_EXPORT Dart_Handle Dart_GetStacktrace(Dart_Handle unhandled_exception);
-
-/**
  * Throws an exception.
  *
- * Throws an exception, unwinding all dart frames on the stack.  If
- * successful, this function does not return.  Note that this means
+ * Throws an exception, unwinding all dart frames on the stack. 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.
+ * called. If there are no Dart frames on the stack, an error occurs.
  *
- * \return An invalid handle if the exception was not thrown.
+ * \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.
  *
- * Rethrows an exception, unwinding all dart frames on the stack.  If
- * successful, this function does not return.  Note that this means
+ * Rethrows an exception, unwinding all dart frames on the stack. 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.
+ * called. If there are no Dart frames on the stack, an error occurs.
  *
- * \return An invalid handle if the exception was not thrown.
+ * \return An error handle if the exception was not thrown.
  *   Otherwise the function does not return.
  */
 DART_EXPORT Dart_Handle Dart_RethrowException(Dart_Handle exception,
                                               Dart_Handle stacktrace);
 
 // --- Native functions ---
 
 /**
  * The arguments to a native function.
  *
@@ skipping 74 matching lines @@
 DART_EXPORT Dart_Handle Dart_CompileAll();
 
 /**
  * Is this object a Library?
  */
 DART_EXPORT bool Dart_IsLibrary(Dart_Handle object);
 
 /**
  * Lookup a class by name from a Library.
  *
- * \return If no errors occur, the Library is returned. Otherwise an
- *   invalid handle is returned.
+ * \return If no error occurs, the Library is returned. Otherwise an
+ *   error handle is returned.
  */
 DART_EXPORT Dart_Handle Dart_GetClass(Dart_Handle library, Dart_Handle name);
 
 DART_EXPORT Dart_Handle Dart_LookupLibrary(Dart_Handle url);
 
 DART_EXPORT Dart_Handle Dart_LibraryUrl(Dart_Handle library);
 DART_EXPORT Dart_Handle Dart_LibraryImportLibrary(Dart_Handle library,
                                                   Dart_Handle import);
 
 DART_EXPORT Dart_Handle Dart_LoadLibrary(Dart_Handle url,
@@ skipping 16 matching lines @@
 
 // --- Profiling support ----
 
 // External pprof support for gathering and dumping symbolic
 // information that can be used for better profile reports for
 // dynamically generated code.
 DART_EXPORT void Dart_InitPprofSupport();
 DART_EXPORT void Dart_GetPprofSymbolInfo(void** buffer, int* buffer_size);
 
 #endif  // INCLUDE_DART_API_H_