Implement more of the mirrors library, primarily stuff to do with types.

runtime/include/dart_api.h

Index: runtime/include/dart_api.h
===================================================================
--- runtime/include/dart_api.h	(revision 11702)
+++ runtime/include/dart_api.h	(working copy)
@@ -1952,7 +1952,7 @@
 /**
  * Retrieves the function of a closure.
  *
- * \return A handle on the function of the closure, or an error handle if the
+ * \return A handle to the function of the closure, or an error handle if the
  *   argument is not a closure.
  */
 DART_EXPORT Dart_Handle Dart_ClosureFunction(Dart_Handle closure);
@@ -2040,6 +2040,39 @@
 DART_EXPORT Dart_Handle Dart_ClassGetInterfaceAt(Dart_Handle clazz,
                                                  intptr_t index);
 
+/**
+ * Is this class defined by a typedef?
+ *
+ * Typedef definitions from the main program are represented as a
+ * special kind of class handle.  These typedef classes allow the

[cshapiro, 2012/09/12 18:52:07]

typedef classes or typedef class handles?

[turnidge, 2012/09/12 21:39:30]

Done.

+ * embedder to find their referent by using
+ * Dart_ClassGetTypedefReferent.

[cshapiro, 2012/09/12 18:52:07]

Wordy.

"Dart_ClassGetTypedefReferent returns the class handle referent."

[turnidge, 2012/09/12 21:39:30]

Made less wordy.

+ *
+ * TODO(turnidge): Finish documentation.
+ */
+DART_EXPORT bool Dart_ClassIsTypedef(Dart_Handle handle);

[cshapiro, 2012/09/12 18:52:07]

Rename "handle" to "klass", "cls", or "clazz" ?

+
+/**
+ * Returns a handle to the type to which a typedef refers.
+ *
+ * This function should only be called when Dart_ClassIsTypedef returns
+ * true.

[cshapiro, 2012/09/12 18:52:07]

Why?  I would expect this function to return an error if a precondition is
violated.

[turnidge, 2012/09/12 21:39:30]

Just so.  I'm telling them how to avoid getting an error.  Changed the wording
to be more explicit:

 * It is an error to call this function on a handle for which
 * Dart_ClassIsTypedef is not true.

+ *
+ * TODO(turnidge): Finish documentation.
+ */
+DART_EXPORT Dart_Handle Dart_ClassGetTypedefReferent(Dart_Handle clazz);
+
+/**
+ * Does this class represent the type of a function?
+ */
+DART_EXPORT bool Dart_ClassIsFunctionType(Dart_Handle handle);

[cshapiro, 2012/09/12 18:52:07]

Rename "handle" to "klass", "cls", or "clazz" ?

[turnidge, 2012/09/12 21:39:30]

Done.

+
+/**
+ * Returns a signature function for a function type.

[cshapiro, 2012/09/12 18:52:07]

signature function or function signature?

[turnidge, 2012/09/12 21:39:30]

Um, rewrote comment entirely:


/**
 * Returns a function handle representing the signature associated
 * with a function type.
 *
 * The return value is a function handle (See Dart_IsFunction, etc.).
 *
 * TODO(turnidge): Finish documentation.
 */

+ */
+DART_EXPORT Dart_Handle Dart_ClassGetFunctionTypeSignature(Dart_Handle clazz);
+
+
 // --- Function and Variable Declarations ---
 
 /**
@@ -2049,7 +2082,7 @@
  * \param target A library or class.
  *
  * \return If no error occurs, a list of strings is returned.
- *   Otherwise an erorr handle is returned.
+ *   Otherwise an error handle is returned.
  */
 DART_EXPORT Dart_Handle Dart_GetFunctionNames(Dart_Handle target);
 
@@ -2076,19 +2109,21 @@
  * Returns the name for the provided function or method.
  *
  * \return A valid string handle if no error occurs during the
- * operation.
+ *   operation.
  */
 DART_EXPORT Dart_Handle Dart_FunctionName(Dart_Handle function);
 
 /**
- * Returns a handle to the owner of a function. The owner of an instance method
- * or a static method is its defining class. The owner of a top-level function
- * is its defining library. The owner of the function of a non-implicit closure
- * is the function of the method or closure that defines the non-implicit
+ * Returns a handle to the owner of a function.
+ *
+ * The owner of an instance method or a static method is its defining
+ * class. The owner of a top-level function is its defining
+ * library. The owner of the function of a non-implicit closure is the
+ * function of the method or closure that defines the non-implicit
  * closure.
  *
- * \return A valid handle on the owner of the function, or an error handle if
- * the argument is not a valid handle to a function.
+ * \return A valid handle to the owner of the function, or an error
+ *   handle if the argument is not a valid handle to a function.
  */
 DART_EXPORT Dart_Handle Dart_FunctionOwner(Dart_Handle function);
 
@@ -2153,6 +2188,14 @@
                                               bool* is_setter);
 
 /**
+ * Returns a handle to the return type of a function.

[cshapiro, 2012/09/12 18:52:07]

I am confused about the pervasive use of handle in this documentation.  The
handle seems implied.

[turnidge, 2012/09/12 21:39:30]

Right.  I am torn about this.  I could start dropping the handles all over the
documentation which might make it all read easier.  I take it you think this is
a good idea?

[cshapiro, 2012/09/13 04:29:58]

I think the handle is superfluous, after all what else could it be?  Also, the
inconsistent usage is a little bit confusing in the context of a reflection API
given the indirection inherent in many of these operations.

[turnidge, 2012/09/13 17:02:57]

Fixed this use.  Will fix the more pervasive problem in a follow-up CL.

+ *
+ * \return A valid handle to a type or an error handle if the argument
+ *   is not valid.
+ */
+DART_EXPORT Dart_Handle Dart_FunctionReturnType(Dart_Handle function);
+
+/**
  * Determines the number of required and optional parameters.
  *
  * \param function A handle to a function or method declaration.
@@ -2167,20 +2210,29 @@
   int64_t* opt_param_count);
 
 /**
+ * Returns a handle to the type of a function parameter.
+ *
+ * \return A valid handle to a type or an error handle if the argument
+ *   is not valid.
+ */
+DART_EXPORT Dart_Handle Dart_FunctionParameterType(Dart_Handle function,
+                                                   int parameter_index);
+
+/**
  * Returns a list of the names of all variables declared in a library
  * or class.
  *
  * \param target A library or class.
  *
  * \return If no error occurs, a list of strings is returned.
- *   Otherwise an erorr handle is returned.
+ *   Otherwise an error handle is returned.
  */
 DART_EXPORT Dart_Handle Dart_GetVariableNames(Dart_Handle target);
 
 /**
  * Looks up a variable declaration by name from a library or class.
  *
- * \param library The library or class containing the variable.
+ * \param target The library or class containing the variable.
  * \param variable_name The name of the variable.
  *
  * \return If an error is encountered, returns an error handle.
@@ -2225,6 +2277,70 @@
 DART_EXPORT Dart_Handle Dart_VariableIsFinal(Dart_Handle variable,
                                              bool* is_final);
 
+/**
+ * Returns a handle to the type of a variable.
+ *
+ * \return A valid handle to a type of or an error handle if the
+ *   argument is not valid.
+ */
+DART_EXPORT Dart_Handle Dart_VariableType(Dart_Handle function);
+
+/**
+ * Returns a list of the names of all type variables declared in a class.
+ *
+ * The type variables list preserves the original declaration order.
+ *
+ * \param clazz A class.
+ *
+ * \return If no error occurs, a list of strings is returned.
+ *   Otherwise an error handle is returned.
+ */
+DART_EXPORT Dart_Handle Dart_GetTypeVariableNames(Dart_Handle clazz);
+
+/**
+ * Looks up a type variable declaration by name from a class.
+ *
+ * \param clazz The class containing the type variable.
+ * \param variable_name The name of the type variable.
+ *
+ * \return If an error is encountered, returns an error handle.
+ *   Otherwise returns a type variable handle if the type variable is
+ *   found or Dart_Null() if the type variable is not found.
+ */
+DART_EXPORT Dart_Handle Dart_LookupTypeVariable(Dart_Handle clazz,
+                                                Dart_Handle type_variable_name);
+
+/**
+ * Is this a type variable handle?
+ */
+DART_EXPORT bool Dart_IsTypeVariable(Dart_Handle handle);
+
+/**
+ * Returns the name for the provided type variable.
+ */
+DART_EXPORT Dart_Handle Dart_TypeVariableName(Dart_Handle type_variable);
+
+/**
+ * Returns a handle to the owner of a function.
+ *
+ * The owner of a type variable is its defining class.
+ *
+ * \return A valid handle to the owner of the type variable, or an error
+ *   handle if the argument is not a valid handle to a type variable.
+ */
+DART_EXPORT Dart_Handle Dart_TypeVariableOwner(Dart_Handle type_variable);
+
+/**
+ * Returns a handle to the upper bound of a type variable.
+ *
+ * The upper bound of a type variable is ...
+ *
+ * \return A valid handle to a type, or an error handle if the
+ *   argument is not a valid handle.
+ */
+DART_EXPORT Dart_Handle Dart_TypeVariableUpperBound(Dart_Handle type_variable);
+// TODO(turnidge): Finish documentation.
+
 // --- Constructors, Methods, and Fields ---
 
 /**
@@ -2542,7 +2658,7 @@
  * in a library.
  *
  * \return If no error occurs, a list of strings is returned.
- *   Otherwise an erorr handle is returned.
+ *   Otherwise an error handle is returned.
  */
 DART_EXPORT Dart_Handle Dart_LibraryGetClassNames(Dart_Handle library);