Document the getSourceReport rpc in service.md. Bump version to 3.1.

runtime/vm/service/service.md

-# Dart VM Service Protocol 3.0
+# Dart VM Service Protocol 3.1
 
 > Please post feedback to the [observatory-discuss group][discuss-list]
 
-This document describes of _version 3.0_ of the Dart VM Service Protocol. This
+This document describes of _version 3.1_ 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][].
 
 [JSON-RPC 2.0]: http://www.jsonrpc.org/specification
 
 **Table of Contents**
 
 - [RPCs, Requests, and Responses](#rpcs-requests-and-responses)
 - [Events](#events)
 - [Types](#types)
 - [IDs and Names](#ids-and-names)
 - [Versioning](#versioning)
 - [Private RPCs, Types, and Properties](#private-rpcs-types-and-properties)
 - [Public RPCs](#public-rpcs)
         - [addBreakpoint](#addbreakpoint)
         - [addBreakpointWithScriptUri](#addbreakpointwithscripturi)
         - [addBreakpointAtEntry](#addbreakpointatentry)
         - [evaluate](#evaluate)
         - [evaluateInFrame](#evaluateinframe)
         - [getFlagList](#getflaglist)
         - [getIsolate](#getisolate)
         - [getObject](#getobject)
+        - [getSourceReport](#getsourcereport)
         - [getStack](#getstack)
         - [getVersion](#getversion)
         - [getVM](#getvm)
         - [pause](#pause)
         - [removeBreakpoint](#removebreakpoint)
         - [resume](#resume)
         - [setExceptionPauseMode](#setexceptionpausemode)
         - [setLibraryDebuggable](#setlibrarydebuggable)
         - [setName](#setname)
         - [setVMName](#setvmname)
@@ skipping 25 matching lines @@
         - [LibraryDependency](#librarydependency)
         - [MapAssociation](#mapassociation)
         - [Message](#message)
         - [Null](#null)
         - [Object](#object)
         - [Response](#response)
         - [Sentinel](#sentinel)
         - [SentinelKind](#sentinelkind)
         - [Script](#script)
         - [SourceLocation](#sourcelocation)
+        - [SourceReport](#sourcereport)
+        - [SourceReportCoverage](#sourcereportcoverage)
+        - [SourceReportKind](#sourcereportkind)
+        - [SourceReportRange](#sourcereportrange)
         - [Stack](#stack)
         - [StepOption](#stepoption)
         - [Success](#success)
         - [TypeArguments](#typearguments)
         - [UresolvedSourceLocation](#unresolvedsourcelocation)
         - [Version](#version)
         - [VM](#vm)
 - [Revision History](#revision-history)
 
 ## RPCs, Requests, and Responses
@@ skipping 470 matching lines @@
 
 ```
 Stack getStack(string isolateId)
 ```
 
 The _getStack_ RPC is used to retrieve the current execution stack and
 message queue for an isolate. The isolate does not need to be paused.
 
 See [Stack](#stack).
 
+### getSourceReport
+
+```
+SourceReport getSourceReport(string isolateId,
+                             SourceReportKind[] reports,
+                             string scriptId [optional],
+                             int tokenPos [optional],
+                             int endTokenPos [optional],
+                             bool forceCompile [optional])
+```
+
+The _getSourceReport_ RPC is used to generate a set of reports tied to
+source locations in an isolate.
+
+The _reports_ parameter is used to specify which reports should be
+generated.  The _reports_ parameter is a list, which allows multiple
+reports to be generated simultaneously from a consistent isolate
+state.  The _reports_ parameter is allowed to be empty (this might be
+used to force compilation of a particular subrange of some script).
+
+The available report kinds are:
+
+report kind | meaning
+----------- | -------
+Coverage | Provide code coverage information
+PossibleBreakpoints | Provide a list of token positions which correspond to possible breakpoints.
+
+The _scriptId_ parameter is used to restrict the report to a
+particular script.  When analyzing a particular script, either or both
+of the _tokenPos_ and _endTokenPos_ parameters may be provided to
+restrict the analysis to a subrange of a script (for example, these
+can be used to restrict the report to the range of a particular class
+or function).
+
+If the _scriptId_ parameter is not provided then the reports are
+generated for all loaded scripts and the _tokenPos_ and _endTokenPos_
+parameters are disallowed.
+
+The _forceCompilation_ parameter can be used to force compilation of
+all functions in the range of the report.  Forcing compilation can
+have semantic side effects on the running Dart program.  If this

[rmacnak, 2016/01/28 21:45:09]

Consider specifically mentions early termination from compilation errors.

+parameter is not provided, it is considered to have the value _false_.
+
+See [SourceReport](#sourcereport).
+
 ### getVersion
 
 ```
 Version getVersion()
 ```
 
 The _getVersion_ RPC is used to determine what version of the Service Protocol is served by a VM.
 
 See [Version](#version).
 
@@ skipping 1562 matching lines @@
   int tokenPos;
 
   // The last token of the location if this is a range.
   int endTokenPos [optional];
 }
 ```
 
 The _SourceLocation_ class is used to designate a position or range in
 some script.
 
+### SourceReport
+
+```
+class SourceReport extends Response {
+  // A list of ranges in the program source.  These ranges correspond
+  // to ranges of executable code in the user's program (functions,
+  // methods, constructors, etc.)
+  //
+  // Note that ranges may nest in other ranges, in the case of nested
+  // functions.
+  //
+  // Note that ranges may be duplicated, in the case of mixins.
+  SourceReportRange[] ranges;
+
+  // A list of scripts, referenced by index in the report's ranges.
+  ScriptRef[] scripts;
+}
+```
+
+The _SourceReport_ class represents a set of reports tied to source
+locations in an isolate.
+
+### SourceReportCoverage
+
+```
+class SourceReportCoverage {
+  // A list of token positions in a SourceReportRange which have been
+  // executed.  The list is sorted.
+  int[] hits;
+
+  // A list of token positions in a SourceReportRange which have not been
+  // executed.  The list is sorted.
+  int[] misses;
+}
+```
+
+The _SourceReportCoverage_ class represents coverage information for
+one [SourceReportRange](#sourcereportrange).
+
+Note that _SourceReportCoverage_ does not extend [Response](#response)
+and therefore will not contain a _type_ property.
+
+### SourceReportKind
+
+```
+enum SourceReportKind {
+  // Used to request a code coverage information.
+  Coverage,
+
+  // Used to request a list of token positions of possible breakpoints.
+  PossibleBreakpoints
+}
+```
+
+### SourceReportRange
+
+```
+class SourceReportRange {
+  // An index into the script table of the SourceReport, indicating
+  // which script contains this range of code.
+  int scriptIndex;
+
+  // The token position at which this range begins.
+  int startPos;
+
+  // The token position at which this range ends.  Inclusive.
+  int endPos;
+
+  // Has this range been compiled by the Dart VM?
+  bool compiled;
+
+  // Code coverage information for this range.  Provided only when the
+  // Coverage report has been requested and the range has been
+  // compiled.
+  SourceReportCoverage coverage [optional];
+
+  // Possible breakpoint information for this range, represented as a
+  // sorted list of token positions.  Provided only when the when the
+  // PossibleBreakpoint report has been requested and the range has been
+  // compiled.
+  int possibleBreakpoints[] [optional];
+}
+```
+
+The _SourceReportRange_ class represents a range of executable code
+(function, method, constructor, etc) in the running program.  It is
+part of a [SourceReport](#sourcereport).
+
+Note that _SourceReportRange_ does not extend [Response](#response)
+and therefore will not contain a _type_ property.
+
 ### Stack
 
 ```
 class Stack extends Response {
   Frame[] frames;
   Message[] messages;
 }
 ```
 
 ### ExceptionPauseMode
@@ skipping 148 matching lines @@
 }
 ```
 
 ## Revision History
 
 version | comments
 ------- | --------
 1.0 | initial revision
 2.0 | Describe protocol version 2.0.
 3.0 | Describe protocol version 3.0.  Added UnresolvedSourceLocation.  Added Sentinel return to getIsolate.  Add AddedBreakpointWithScriptUri.  Removed Isolate.entry. The type of VM.pid was changed from string to int.  Added VMUpdate events.  Add offset and count parameters to getObject() and offset and count fields to Instance. Added ServiceExtensionAdded event.
+3.1 | Add the getSourceReport RPC.
 
 
 [discuss-list]: https://groups.google.com/a/dartlang.org/forum/#!forum/observatory-discuss