Support column-based breakpoints in the VM and Observatory.

runtime/vm/service/service.md

-# Dart VM Service Protocol 2.0
+# Dart VM Service Protocol 3.0
 
 > Please post feedback to the [observatory-discuss group][discuss-list]
 
-This document describes of _version 2.0_ of the Dart VM Service Protocol. This
+This document describes of _version 3.0_ of the Dart VM Service Protocol. This
 protocol is used to communicate with a running Dart Virtual Machine.
 
 To use the Service Protocol, start the VM with the *--observe* flag.
 The VM will start a webserver which services protocol requests via WebSocket.
 It is possible to make HTTP (non-WebSocket) requests,
 but this does not allow access to VM _events_ and is not documented
 here.
 
 The Service Protocol uses [JSON-RPC 2.0][].
 
@@ skipping 45 matching lines @@
         - [Frame](#frame)
         - [Function](#function)
         - [Instance](#instance)
         - [Isolate](#isolate)
         - [Library](#library)
         - [LibraryDependency](#librarydependency)
         - [MapAssociation](#mapassociation)
         - [Message](#message)
         - [Null](#null)
         - [Object](#object)
+        - [Response](#response)
         - [Sentinel](#sentinel)
         - [SentinelKind](#sentinelkind)
         - [Script](#script)
         - [SourceLocation](#sourcelocation)
         - [Stack](#stack)
         - [StepOption](#stepoption)
         - [Success](#success)
         - [TypeArguments](#typearguments)
-        - [Response](#response)
+        - [UresolvedSourceLocation](#unresolvedsourcelocation)
         - [Version](#version)
         - [VM](#vm)
 - [Revision History](#revision-history)
 
 ## RPCs, Requests, and Responses
 
 An RPC request is a JSON object sent to the server. Here is an
 example [getVersion](#getversion) request:
 
 ```
@@ skipping 12 matching lines @@
 _id_ property to pair it with the corresponding request. If the RPC
 was successful, the _result_ property provides the result.
 
 Here is an example response for our [getVersion](#getversion) request above:
 
 ```
 {
   "jsonrpc": "2.0",
   "result": {
     "type": "Version",
-    "major": 2,
+    "major": 3,
     "minor": 0
   }
   "id": "1"
 }
 ```
 
 Parameters for RPC requests are always provided as _named_ parameters.
 The JSON-RPC spec provides for _positional_ parameters as well, but they
 are not supported by the Dart VM.
 
@@ skipping 169 matching lines @@
 
 ## Versioning
 
 The [getVersion](#getversion) RPC can be used to find the version of the protocol
 returned by a VM. The _Version_ response has a major and a minor
 version number:
 
 ```
   "result": {
     "type": "Version",
-    "major": 2,
+    "major": 3,
     "minor": 0
   }
 ```
 
 The major version number is incremented when the protocol is changed
 in a potentially _incompatible_ way. An example of an incompatible
 change is removing a non-optional property from a result.
 
 The minor version number is incremented when the protocol is changed
 in a _backwards compatible_ way. An example of a backwards compatible
@@ skipping 51 matching lines @@
 ReturnType methodName(parameterType parameterName [optional)
 ```
 
 A description of the return types and parameter types is provided
 in the section on [public types](#public-types).
 
 ### addBreakpoint
 
 ```
 Breakpoint addBreakpoint(string isolateId,
-                         string scriptId,
-                         int line)
+                         string scriptId [optional],
+                         string scriptUri [optional],
+                         int line,
+                         int column [optional])
 ```
 
 The _addBreakpoint_ RPC is used to add a breakpoint at a specific line
 of some script.
 
+The _scriptId_ or _scriptUri_ parameter is used to specify the target
+script. One of these two parameters must always be provided.
+
+The _line_ parameter is used to specify the target line for the
+breakpoint. If there are multiple possible breakpoints on the target
+line, then the VM will place the breakpoint at the location which
+would execute soonest. If it is not possible to set a breakpoint at
+the target line, the breakpoint will be added at the next possible
+breakpoint location within the same function.
+
+The _column_ parameter may be optionally specified.  This is useful
+for targeting a specific breakpoint on a line with multiple possible
+breakpoints.
+
 If no breakpoint is possible at that line, the _102_ (Cannot add
 breakpoint) error code is returned.
 
 Note that breakpoints are added and removed on a per-isolate basis.
 
 See [Breakpoint](#breakpoint).
 
 ### addBreakpointAtEntry
 
 ```
@@ skipping 361 matching lines @@
 
 If the variable has been optimized out by the compiler, the _value_
 will be the _OptimizedOut_ [Sentinel](#sentinel).
 
 ### Breakpoint
 
 ```
 class Breakpoint extends Object {
   int breakpointNumber;
   bool resolved;
-  SourceLocation location;
+  SourceLocation|UnresolvedSourceLocation location;
 }
 ```
 
 A _Breakpoint_ describes a debugger breakpoint.
 
 ### Class
 
 ```
 class @Class extends @Object {
   // The name of this class.
@@ skipping 1007 matching lines @@
   //
   // 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];
 }
 ```
 
 An _Object_ is a  persistent object that is owned by some isolate.
 
+### Response
+
+```
+class Response {
+  // Every response returned by the VM Service has the
+  // type property. This allows the client distinguish
+  // between different kinds of responses.
+  string type;
+}
+```
+
+Every non-error response returned by the Service Protocol extends _Response_.
+By using the _type_ property, the client can determine which [type](#types)
+of response has been provided.
+
 ### Sentinel
 
 ```
 class Sentinel extends Response {
   // What kind of sentinel is this?
   SentinelKind kind;
 
   // A reasonable string representation of this sentinel.
   string valueAsString;
 }
@@ skipping 148 matching lines @@
   //
   // The value will always be one of the kinds:
   // Type, TypeRef, TypeParameter, BoundedType.
   @Instance[] types;
 }
 ```
 
 A _TypeArguments_ object represents the type argument vector for some
 instantiated generic type.
 
-### Response
+### UnresolvedSourceLocation
 
 ```
-class Response {
-  // Every response returned by the VM Service has the
-  // type property. This allows the client distinguish
-  // between different kinds of responses.
-  string type;
+class UnresolvedSourceLocation extends Response {
+  // The script containing the source location if the script has been loaded.
+  @Script script [optional];
+
+  // The uri of the script containing the source location if the script
+  // has yet to be loaded.
+  string scriptUri [optional];
+
+  // An approximate token position for the source location.  This may  
+  // change when the location is resolved.
+  int tokenPos [optional];
+
+  // An approximate line number for the source location.  This may  
+  // change when the location is resolved.
+  int line [optional];
+
+  // An approximate column number for the source location.  This may  
+  // change when the location is resolved.
+  int column [optional];
+
 }
 ```
 
-Every non-error response returned by the Service Protocol extends _Response_.
-By using the _type_ property, the client can determine which [type](#types)
-of response has been provided.
+The _UnresolvedSourceLocation_ class is used to refer to an unresolved
+breakpoint location.  As such, it is meant to approximate the final
+location of the breakpoint but it is not exact.
+
+Either the _script_ or the _scriptUri_ field will be present.
+
+Either the _tokenPos_ or the _line_ field will be present.
+
+The _column_ field will only be present when the breakpoint was
+specified with a specific column number.
 
 ### Version
 
 ```
 class Version extends Response {
   // The major version number is incremented when the protocol is changed
   // in a potentially incompatible way.
   int major;
 
   // The minor version number is incremented when the protocol is changed
@@ skipping 31 matching lines @@
   // A list of isolates running in the VM.
   @Isolate[] isolates;
 }
 ```
 
 ## Revision History
 
 version | comments
 ------- | --------
 1.0 draft 1 | initial revision
+1.1 | Describe protocol version 2.0.
+1.2 | Describe protocol version 3.0.  Added UnresolvedSourceLocation.
 
 
 [discuss-list]: https://groups.google.com/a/dartlang.org/forum/#!forum/observatory-discuss