Service cleanups...

runtime/vm/service/service.md

Index: runtime/vm/service/service.md
diff --git a/runtime/vm/service/service.md b/runtime/vm/service/service.md
index 534fac660e26511b5027f299a27726b183ebfd13..54d39d56764034b64323d723cad25bee7d2320d5 100644
--- a/runtime/vm/service/service.md
+++ b/runtime/vm/service/service.md
@@ -49,7 +49,10 @@ apparently outside the scope of the JSON-RPC specification.
 	- [ClassList](#classlist)
 	- [Code](#code)
 	- [CodeKind](#codekind)
+	- [Context](#context)
+	- [ContextElement](#contextelement)
 	- [Error](#error)
+	- [ErrorKind](#errorkind)
 	- [Event](#event)
 	- [EventKind](#eventkind)
 	- [Field](#field)
@@ -61,7 +64,7 @@ apparently outside the scope of the JSON-RPC specification.
 	- [Isolate](#isolate)
 	- [Library](#library)
 	- [LibraryDependency](#librarydependency)
-	- [ListElement](#listelement)
+	- [MapAssociation](#mapassociation)
 	- [Message](#message)
 	- [Null](#null)
 	- [Object](#object)
@@ -869,7 +872,15 @@ class Context {
   int length;
 
   // The variables in this context object.
-  ListElement[] variables;
+  ContextElement[] variables;
+}
+```
+
+### ContextElement
+
+```
+class ContextElement {
+  @Instance|Sentinel value;
 }
 ```
 
@@ -877,6 +888,9 @@ class Context {
 
 ```
 class @Error extends @Object {
+  // What kind of error is this?
+  ErrorKind kind;
+
   // A description of the error.
   string message;
 }
@@ -886,6 +900,9 @@ _@Error_ is a reference to an _Error_.
 
 ```
 class Error extends Object {
+  // What kind of error is this?
+  ErrorKind kind;
+
   // A description of the error.
   string message;
 
@@ -902,12 +919,24 @@ class Error extends Object {
 An _Error_ represents a Dart language level error.  This is distinct from an
 [rpc error](#rpc-error).
 
-An error may occur when:
+### ErrorKind
+
+```
+enum ErrorKind {
+  // The isolate has encountered an unhandled Dart exception.
+  UnhandledException,
+
+  // The isolate has encountered a Dart language error in the program.
+  LanguageError,
 
-- The program has encountered an unhandled exception
-- The program has encountered a syntax error (or another Dart language error)
-- The program has encountered an unhandled erroneous condition in native code
-- The program has been terminated
+  // The isolate has encounted an internal error.  These errors should be
+  // reported as bugs.
+  InternalError,
+
+  // The isolate has been terminated by an external source.
+  TerminationError
+}
+```
 
 ### Event
 
@@ -919,7 +948,7 @@ class Event extends Response {
   // The isolate with which this event is associated.
   @Isolate isolate;
 
-  // The breakpoint associated with this event, if applicable.
+  // The breakpoint which was added, removed, or resolved.
   //
   // This is provided for the event kinds:
   //   PauseBreakpoint
@@ -928,6 +957,19 @@ class Event extends Response {
   //   BreakpointResolved
   Breakpoint breakpoint [optional];
 
+  // The list of breakpoints at which we are currently paused
+  // for a PauseBreakpoint event.
+  //
+  // This list may be empty.  For example, while single-stepping, the
+  // VM sends a PauseBreakpoint event with no breakpoints.
+  //
+  // If there is more than one breakpoint set at the program position,
+  // then all of them will be provided.
+  //
+  // This is provided for the event kinds:
+  //   PauseBreakpoint
+  Breakpoint[] pauseBreakpoints [optional];
+
   // The top stack frame associated with this event, if applicable.
   //
   // This is provided for the event kinds:
@@ -1161,7 +1203,7 @@ class @Instance extends @Object {
   // What kind of instance is this?
   InstanceKind kind;
 
-  // Instance references include their class.
+  // Instance references always include their class.
   @Class class;
 
   // The value of this instance as a string.
@@ -1211,7 +1253,7 @@ class Instance extends Object {
   // What kind of instance is this?
   InstanceKind kind;
 
-  // Instance references include their class.
+  // Instance references always include their class.
   @Class class;
 
   // The value of this instance as a string.
@@ -1258,7 +1300,7 @@ class Instance extends Object {
   //
   // Provided for instance kinds:
   //   List
-  ListElement[] elements [optional];
+  @Instance|Sentinel[] elements [optional];
 
   // The elements of a List instance.
   //
@@ -1309,7 +1351,14 @@ class Instance extends Object {
   int parameterIndex [optional];
 
   // The type bounded by a BoundedType instance
-  // or
+  //
+  // The value will always be one of:
+  // Type, TypeRef, TypeParameter, BoundedType.
+  //
+  // Provided for instance kinds:
+  //   BoundedType
+  @Instance boundedType [optional];
+
   // The referent of a TypeRef instance.
   //
   // The value will always be one of:
@@ -1318,7 +1367,7 @@ class Instance extends Object {
   // Provided for instance kinds:
   //   BoundedType
   //   TypeRef
-  @Instance type [optional];
+  @Instance referentType [optional];
 
   // The bound of a TypeParameter or BoundedType.
   //
@@ -1521,15 +1570,6 @@ class LibraryDependency {
 
 A _LibraryDependency_ provides information about an import or export.
 
-### ListElement
-
-```
-class ListElement {
-  int index;
-  @Instance|Sentinel value;
-}
-```
-
 ### MapAssociation
 
 ```
@@ -1592,13 +1632,24 @@ class Object extends Response {
   // Some objects may get a new id when they are reloaded.
   string id;
 
-  // Every object has a corresponding Class in the VM.
-  @Class class;
+  // If an object is allocated in the Dart heap, it will have
+  // a corresponding class object.
+  //
+  // The class of a non-instance is not a Dart class, but is instead
+  // an internal vm object.
+  //
+  // Moving an Object into or out of the heap is considered a
+  // backwards compatible change for types other than Instance.
+  @Class class [optional];
 
   // The size of this object in the heap.
   //
-  // Note that the size can be zero for some objects.
-  int size;
+  // If an object is not heap-allocated, then this field is omitted.
+  //
+  // Note that the size can be zero for some objects.  In the current
+  // VM implementation, this occurs for small integers, which are
+  // stored entirely within their object pointers.
+  int size [optional];
 }
 ```