Reorganize dart_api.h and add a bunch of documentation.

runtime/vm/dart_api_impl.cc

 // 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.
 
 #include "include/dart_api.h"
 
 #include "vm/bigint_operations.h"
 #include "vm/class_finalizer.h"
 #include "vm/compiler.h"
 #include "vm/dart.h"
@@ skipping 1842 matching lines @@
 }
 
 
 static uint8_t* allocator(uint8_t* ptr, intptr_t old_size, intptr_t new_size) {
   void* new_ptr = realloc(reinterpret_cast<void*>(ptr), new_size);
   return reinterpret_cast<uint8_t*>(new_ptr);
 }
 
 
 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);
 }
 
 
 DART_EXPORT bool Dart_Post(Dart_Port port, Dart_Handle handle) {
   Zone zone;  // Setup a VM zone as we are creating some handles.
   HandleScope scope;  // Setup a VM handle scope.
   const Object& object = Object::Handle(Api::UnwrapHandle(handle));
@@ skipping 120 matching lines @@
   ASSERT(isolate != NULL);
   ApiState* state = isolate->api_state();
   ASSERT(state != NULL);
   ApiLocalScope* scope = state->top_scope();
   ASSERT(scope != NULL);
   return scope->zone().Reallocate(ptr, old_size, new_size);
 }
 
 
 }  // namespace dart