Rework how types work in the VM Service.

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
 
@@ skipping 25 matching lines @@
     {
       type: "Isolate",
       id: "isolates/123",
       name: "worker"
       entry: ...
       heaps: ...
       topFrame: ...
       ...
     }
 
+## Type Hierarchy
+
+The types returned by the VM Service fit into a type hierarchy, with a
+subtyping relationship as indicated by the following indented list:
+
+<pre>
+Object
+    ClassHeapStats
+    Class
+    Code
+    Context
+    Counter
+    Error
+    Field
+    FrameVar
+    Frame
+    Function
+    Gauge
+    Instance
+        AbstractType
+            BoundedType
+            TypeParameter
+            TypeRef
+            Type
+        List
+        Sentinel  // TODO - subtype of Instance or not?
+        String
+        bool
+        double
+        int
+        null
+    Isolate
+    Library
+    Location
+    Script
+    ServiceError
+    ServiceEvent
+    Socket
+    TypeArguments  // TODO - expose?
+    VM
+</pre>
+
+TODO: How to put links in a pre in markdown?
+
+A subtype is guaranteed to provide all of the properties of its
+parent type.  For example, an [int](#int) can be used as an
+[Instance](#Instance).
+
+The subtyping relationship also holds for reference types.  For
+example, [@int](#int) can be used as an [@Instance](#Instance).
+
 ## 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.  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>.
@@ skipping 23 matching lines @@
 
 ## 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.
+## Private Properties
+
+Some properties returned by the VM Service begin with an underscore
+(<code>_</code>) character.  These properties are called _private
+properties_.  Private properties provide private information about the
+VM's implemention.  Private properties may be added, removed, or

[koda, 2014/09/05 21:29:29]

implemention -> implementation

[turnidge, 2014/09/08 16:20:19]

Done.

+changed at any time with any release of the VM.  They are provided for
+those tools that need this level of internal access, such as the
+Observatory.
+
+For example, some responses will have the <code>_vmType</code>
+property.  This provides the vm-internal type name of an object, and

[koda, 2014/09/05 21:29:29]

Be consistent w.r.t. vm/VM.

[turnidge, 2014/09/08 16:20:19]

Done.

+is provided only when it this type name differs from the
+<code>type</code> property.
 
 ## Events
 
 TODO
 
 ## Catalog of Types
 
 ### <a name="AbstractType"></a>AbstractType
 
 ### <a name="Breakpoint"></a>Breakpoint
@@ skipping 13 matching lines @@
 
 ### <a name="Class"></a>Class
 
 Reference properties:
 
 | keys | values | comments
 | --- | --- | ---
 | type | "@Class", "Class" |
 | id | String |
 | name | String |
-| vmName? | String |
+| _vmName? | String |
 
 Object properties:
 
 | keys | values | comments
 | --- | --- | ---
 | error? | [Error](#Error) | Error encountered during class finalization
 | implemented | bool |
 | abstract | bool |
 | patch | bool |
 | finalized | bool |
@@ skipping 39 matching lines @@
 
 ### <a name="Code"></a>Code
 
 Reference properties:
 
 | keys | values | comments
 | --- | --- | ---
 | type | "@Code", "Code"|
 | id | String |
 | name | String |
-| vmName? | String |
+| _vmName? | String |
 | start | String | starting address of code
 | end | String | ending address of code
 | isOptimized | bool |
 | isAlive | bool |
 | kind | String
 | function | [@Function](#Function) |
 
 Object properties:
 
 | keys | values | comments
@@ skipping 11 matching lines @@
 
 | index | value | description
 | --- | --- | --- |
 | 0 | String | Address of instruction
 | 1 | String | Hex encoding of instruction
 | 2 | String | Human encoding of instruction
 | 0 + (3 * K) | String | Address of Kth instruction
 | 1 + (3 * K) | String | Hex encoding of instruction of Kth instruction
 | 2 + (3 * K) | String | Human encoding of instruction of Kth instruction
 
-### <a name="DebuggerEvent"></a>DebuggerEvent
-
-Object properties:
-
-| keys | values | comments
-| --- | --- | ---
-| type | "DebuggerEvent" |
-| id | String | TODO: Remove |
-| eventType | String | "BreakpointReached", "BreakpointResolved", "ExceptionThrown", "IsolateCreated", "IsolateShutdown", "IsolateInterrupted" |
-| isolate | [@Isolate](#Isolate) |
-| breakpoint? | [Breakpoint](#Breakpoint) | for eventTypes "BreakpointResolved" and "BreakpointReached<br><br>TODO: Maybe make this @Breakpoint?
-| exception? | [@Instance](#Instance) | for eventType "ExceptionThrown"
-
 ### <a name="Error"></a>Error
 
 TODO: Drop id from Error.<br>
 
 Object properties:
 
 | keys | values | comments
 | --- | --- | ---
 | type | "Error" |
+| _vmType? | String | VM internal name for this type.  Provided only when different from 'type'
 | id | String | always empty
 | kind | String |
 | message | String |
 
 ### <a name="Field"></a>Field
 
 Reference properties:
 
 | keys | values | comments
 | --- | --- | ---
 | type | "@Field", "Field" |
 | id | String |
 | name | String |
-| vmName? | String |
+| _vmName? | String |
 | value? | Instance | value associated with static field <-- do we want to include this in a field reference?
 | owner | [@Library](#Library),[@Class](#Class) | Owning library or class <-- handling of owner is inconsistent with Function
 | declared_type | [@AbstractType](#AbstractType) |
 | static | bool |
 | final | bool |
 | const | bool |
 
 Object properties:
 
 | keys | values | comments
@@ skipping 29 matching lines @@
 
 ### <a name="Function"></a>Function
 
 Reference properties:
 
 | keys | values | comments
 | --- | --- | ---
 | type | "@Function", "Function" |
 | id | String |
 | name | String |
-| vmName? | String |
+| _vmName? | String |
 | owningLibrary? | [@Library](#Library) | Set for non-top level functions
 | owningClass? | [@Class](#Class) | Set for non-top level functions
 | parent? | [@Function](#Function) | Parent function
 | kind | String |
 
 Object properties:
 
 | keys | values | comments
 | --- | --- | ---
 | static | bool | TODO: not consistent with Field 
@@ skipping 40 matching lines @@
 
 ### <a name="Library"></a>Library
 
 Reference properties:
 
 | keys | values | comments
 | --- | --- | ---
 | type | "@Library", "Library" |
 | id | String |
 | name | String |
-| vmName? | String | Internal vm name.  Provided only when different from 'name'.
+| _vmName? | String | Internal vm name.  Provided only when different from 'name'.

[koda, 2014/09/05 21:29:29]

VM-internal.

[turnidge, 2014/09/08 16:20:19]

Done.

 | url | String
 
 Object properties:
 
 | keys | values | comments
 | --- | --- | ---
 | classes | List of [@Class](#Class) |
 | imports | List of [@Library](#Library) |
 | variables | List of ... |
 | functions | List of [@Function](#Function) |
 | scripts | List of [@Script](#Script) |
 
 ### <a name="Location"></a>Location
 
 Object properties:
 
 | keys | values | comments
 | --- | --- | ---
 | type | "Location" |
 | script | [@Script](#Script) |
 | tokenPos | int |
 
-### <a name="Null"></a>Null
+### <a name="null"></a>null
 
 Reference properties:
 
 | keys | values | comments
 | --- | --- | ---
-| type | "@Null", "Null" |
+| type | "@null", "null" |
 | id | String | |
 | valueAsString | String |
 
 Object properties:<br>
 
 TODO.
 
+### <a name="Object"></a>Object
+
+An [Object](#Object) is a supertype of any response returned by the VM

[koda, 2014/09/05 21:29:29]

An object is not a type. "Object" is a type. Maybe:

"Object is the supertype of all responses..."

[turnidge, 2014/09/08 16:20:19]

Thanks.  I rewrote this a bunch of times and it got a little incoherent.  I used
your suggestions.

+Service.  It does not necessarily refer to an Object at the Dart
+language level (see [Instance](#Instance)).
+
+Reference properties:
+
+| keys | values | comments
+| --- | --- | ---
+| type | "@Object", "Object" or subtype |
+| _vmType? | String | VM internal name for this type.  Provided only when different from 'type'
+| id | String |
+
+Object properties: none<br>
+
 ### <a name="PcDescriptor"></a>PcDescriptor
 
 ### <a name="Script"></a>Script
 
 Reference properties:
 
 | keys | values | comments | example |
 | --- | --- | ---
 | type | "@Script", "Script" |
 | id | String
 | name | String
-| vmName? | String | Internal vm name.  Provided only when different from 'name'.
+| _vmName? | String | Internal vm name.  Provided only when different from 'name'.
 | kind | String
 
 Object properties:
 
 | keys | values | comments
 | --- | --- | ---
 | owningLibrary | [@Library](#Library)
 | source | String
 | tokenPosTable | List of list of int. See note below about token line format.
 
@@ skipping 14 matching lines @@
 TODO: Should this even have an id?  Maybe a *kind* instead.<br><br>
 
 Object properties:
 
 | keys | values | comments
 | --- | --- | ---
 | type | "Sentinel" |
 | id | String | |
 | valueAsString | String |
 
+### <a name="ServiceEvent"></a>ServiceEvent
+
+Object properties:
+
+| keys | values | comments
+| --- | --- | ---
+| type | "ServiceEvent" |
+| id | String | TODO: Remove |
+| eventType | String | "BreakpointReached", "BreakpointResolved", "ExceptionThrown", "IsolateCreated", "IsolateShutdown", "IsolateInterrupted" |
+| isolate | [@Isolate](#Isolate) |
+| breakpoint? | [Breakpoint](#Breakpoint) | for eventTypes "BreakpointResolved" and "BreakpointReached<br><br>TODO: Maybe make this @Breakpoint?
+| exception? | [@Instance](#Instance) | for eventType "ExceptionThrown"
+
 ### <a name="VM"></a>VM
 
 Object properties:
 
 | keys | values | comments
 | --- | --- | ---
 | type | "VM" |
 | id | String |
 | targetCPU | String |
 | hostCPU | String |
 | date | String | kill? |
 | version | String |
 | pid | int |
 | assertsEnabled | bool | TODO: move to features? |
 | typeChecksEnabled | bool | TODO: move to features? |
 | uptime | double | seconds since vm started |
 | "isolates"    | List of [@Isolate](#Isolate)  |