Add more types to service/protocol.md

runtime/vm/service/protocol.md

 # Dart VM Service Protocol
 
+NOTE: The service api is still changing rapidly.  If you use the
+service api, expect to encounter non-compatible changes.
+
 Description
 How to start
 JSON
 Websocket
 
 ## Types
 
-Every response returned by the VM Service has the <code>type</code> property.  This allows the client distinguish between different kinds of responses.  For example, global information about the VM is encoded in an response of type [VM](#VM) and information about an isolate is encoded in an response of type [Isolate](#Isolate).
+Every response returned by the VM Service has the <code>type</code>
+property.  This allows the client distinguish between different kinds
+of responses.  For example, global information about the VM is encoded
+in an response of type [VM](#VM) and information about an isolate is
+encoded in an response of type [Isolate](#Isolate).
 
-If the type name of a response begins with an <code>@</code> character then that response is a _reference_.  If the type name of a response does not begin with an <code>@</code> character then that response is an _object_ (or sometimes _full object_).  A reference is meant to be a subset of a full object with just enough information for the client to generate a reasonable-looking link.
+If the type name of a response begins with an <code>@</code> character
+then that response is a _reference_.  If the type name of a response
+does not begin with an <code>@</code> character then that response is
+an _object_ (or sometimes _full object_).  A reference is meant to be
+a subset of a full object with just enough information for the client
+to generate a reasonable-looking link.
 
 For example, an isolate reference may look like this...
 
     {
       type: "@Isolate",
       id: "isolates/123",
       name: "worker"
     }
 
 ... and a full isolate object would have additional properties:
 
     {
-      type: "@Isolate",
+      type: "Isolate",
       id: "isolates/123",
       name: "worker"
       entry: ...
       heaps: ...
       topFrame: ...
       ...
     }
  
 ## IDs
 
-Most responses returned by the VM Service have an <code>id</code> property.  An id is used to request an object from the VM.
+Most responses returned by the VM Service have an <code>id</code>
+property.  An id is used to request an object from the VM.  Each id is
+unique; that is to say, If two responses have the same id, they refer
+to the same object.  The converse is not true: the same object may
+occasionally be returned with two different ids.
 
-An id is either _global_ or _relative_.  Global ids can be requested from the VM directly by requesting the uri <code>/{global id}</code>.
+An id is either _global_ or _relative_.  Global ids can be requested
+from the VM directly by requesting the uri <code>/{global id}</code>.
 
 The following is a list of known,  fixed global ids:
 
 | id | uri | type
 | --- | --- | ---
 | vm | /vm | [VM](#VM)
 | flags | /flags | [FlagList](#FlagList)
 
-In addition, all isolates have global ids, but these ids are dynamically generated.  An isolate with an id like <code>isolates/123</code> would be available at the uri <code>/isolates/123</code>.
+In addition, all isolates have global ids, but these ids are
+dynamically generated.  An isolate with an id like
+<code>isolates/123</code> would be available at the uri
+<code>/isolates/123</code>.
 
-Relative ids are used to refer to objects that are owned by an isolate.  Relative ids can be requested from the VM directly by requesting the uri <code>/{isolate&nbsp;id}/{relative&nbsp;id}</code>.
+Relative ids are used to refer to objects that are owned by an
+isolate.  Relative ids can be requested from the VM directly by
+requesting the uri <code>/{isolate&nbsp;id}/{relative&nbsp;id}</code>.
 
-For example, we can get information about a class with id <code>classes/Foo</code> from isolate <code>isolates/123</code> by requesting the uri <code>/isolates/123/classes/Foo</code> from the VM.
+For example, we can get information about a class with id
+<code>classes/Foo</code> from isolate <code>isolates/123</code> by
+requesting the uri <code>/isolates/123/classes/Foo</code> from the VM.
 
-The client must not parse ids -- they must be treated as opaque strings.  We reserve the right to change the ids of objects.
+The client must not parse ids -- they must be treated as opaque
+strings.  We reserve the right to change the ids of objects.
+
+## Names
+
+Many responses have the <code>name</code> property.  Names are
+provided so that objects can be displayed in a way that a Dart
+language programmer would find sensible.
+
+Note that names are not in any way unique.  Many objects will have the
+same name.
+
+Occasionally responses will have the <code>vmName</code> property.
+This represents the internal names used to refer to an object inside
+the VM itself.  The <code>vmName</code> of an object is only provided
+when it differs from the <code>name</code> property; when
+<code>vmName</code> is not present, the client may assume the
+<code>name</code> and <code>vmName</code> are the same.
 
 ## Events
 
 TODO
 
 ## Catalog of Types
+
+### <a name="Breakpoint"></a>Breakpoint
+
+TODO: Get rid of Location or else use it more generally.
+
+| keys | values | comments
+| --- | --- | ---
+| type | "Breakpoint" |
+| id | String |
+| breakpointNumber | int |
+| enabled | bool |
+| resolved | bool |
+| location | [Location](#Location) |
+
+### <a name="DebuggerEvent"></a>DebuggerEvent
+
+| keys | values | comments
+| --- | --- | ---
+| type | "DebuggerEvent" |
+| id | String | TODO: Remove |
+| eventType | String | One of "BreakpointReached", "BreakpointResolved", "ExceptionThrown", "IsolateCreated", "IsolateShutdown", or "IsolateInterrupted" |

[Cutch, 2014/08/26 20:38:43]

Do we need "One of"?

+| isolate | [@Isolate](#atIsolate) |
+| breakpoint? | [Breakpoint](#atBreakpoint) | for eventTypes "BreakpointResolved" and "BreakpointReached<br><br>TODO: Maybe make this @Breakpoint?
+| exception? | [@Instance](#atInstance) | for eventType "ExceptionThrown"
+
+### <a name="Frame"></a>Frame
+
+TODO: Add type and id?<br>
+
+| keys | values | comments
+| --- | --- | ---
+| script | [@Script](#atScript) |
+| tokenPos | int |
+| function | [@Function](#atFunction) |
+| code | [@Code](#atCode) |
+| vars | List of [FrameVar](#FrameVar) |
+
+### <a name="FrameVar"></a>FrameVar

[Cutch, 2014/08/26 20:38:43]

Document this as a 'format' instead of a type.

+
+| keys | values | comments
+| --- | --- | ---
+| name | String |
+| value | [@Instance](#atInstance) |
+
+### <a name="Location"></a>Location
+
+| keys | values | comments
+| --- | --- | ---
+| type | "Location" |
+| script | [@Script](#atScript) |
+| tokenPos | int |
+
+### <a name="@Null"></a>@Null
+
+TODO: Split Null from the other Sentinel types.
+
+| keys | values | comments
+| --- | --- | ---
+| type | "@Null" |
+| id | String | |
+| valueAsString | String |
+
 ### <a name="VM"></a>VM
 
 | keys | values | comments
 | --- | --- | ---
 | type | "VM" |
 | id | String |
 | targetCPU | String |
 | hostCPU | String |
 | date | String | kill? |
 | version | String |
@@ skipping 82 matching lines @@
 
 ### <a name="TokenLine"></a>TokenLine
 | index | value | comments
 | --- | --- | ---
 | 0   | integer | line number
 | 1   | integer | first token position
 | 2   | integer | first column number
 | ... | ... | ...
 | 1 + (2 * k) | integer | kth token position
 | 2 + (2 * k) | integer | kth column number