Reorganize dart_api.h and add a bunch of documentation.

runtime/vm/dart_api_impl.cc

Index: runtime/vm/dart_api_impl.cc
===================================================================
--- runtime/vm/dart_api_impl.cc	(revision 1032)
+++ runtime/vm/dart_api_impl.cc	(working copy)
@@ -1860,12 +1860,12 @@
 
 
 DART_EXPORT bool Dart_PostIntArray(Dart_Port port,
-                                   int field_count,
+                                   intptr_t len,
                                    intptr_t* data) {
   uint8_t* buffer = NULL;
   MessageWriter writer(&buffer, &allocator);
 
-  writer.WriteMessage(field_count, data);
+  writer.WriteMessage(len, data);
 
   // Post the message at the given port.
   return PortMap::PostMessage(port, kNoReplyPort, buffer);