Experimental `getDiagnostics` request (#24480).

pkg/analysis_server/tool/spec/spec_input.html

Index: pkg/analysis_server/tool/spec/spec_input.html
diff --git a/pkg/analysis_server/tool/spec/spec_input.html b/pkg/analysis_server/tool/spec/spec_input.html
index 7c8f75333ad26d9c2642ad2f2c8a60e257816db1..aae4f5ba121d325d5aa5cb8bd1bdd9f1959daaf8 100644
--- a/pkg/analysis_server/tool/spec/spec_input.html
+++ b/pkg/analysis_server/tool/spec/spec_input.html
@@ -1959,6 +1959,25 @@
         </params>
       </notification>
     </domain>
+    <domain name="experimental" experimental="true">

[devoncarew, 2015/11/05 23:04:00]

experimental experimental=true seems redundant. I'm hoping this API or something
like it graduates to stable at some point so we can consume it w/o guarding
against it not existing.

Perhaps move the API to a 'diagnostics' domain? Assuming we think there will be
enough content to justify its own domain.

[pquitslund, 2015/11/05 23:16:49]

Absolutely.  When we're done iterating, we should talk about promoting.
Let's see how this goes.  Totally open to that.

+      <p>
+        The experimental domain contains experimental server APIs.  Experimental
+        APIs are not considered to be part of the analysis server's API, docs are
+        not generated for them and they are subject to change without notice.
+        Because the experimental domain is not part of the analysis server's API,
+        the version number of the API will not be updated when changes are made.
+        Caveat emptor!
+      </p>
+      <request method="getDiagnostics">

[devoncarew, 2015/11/05 23:04:00]

I assume experimental=true is implied here, based on the parent domain? I wonder
if there's value in declaring it here as well, for in case the parent is
refactored.

[pquitslund, 2015/11/05 23:16:49]

Right.  Experimentalness passes down.

+        <p>Return server diagnostics.</p>
+        <result>
+          <field name="contexts">
+            <list><ref>ContextInfo</ref></list>
+            <p>The list of analysis contexts.</p>
+          </field>
+        </result>
+      </request>
+    </domain>
     <types>
       <h2 class="domain"><a name="types">Types</a></h2>
       <p>
@@ -2441,6 +2460,43 @@
           <value><code>PARAMETER</code></value>
         </enum>
       </type>
+      <type name="ContextInfo" experimental="true">

[Brian Wilkerson, 2015/11/05 22:43:44]

Given that there's already a class named ContextInfo, it might be better to
rename this. One suggestion would be ContextData.

[pquitslund, 2015/11/05 22:58:11]

Done.

+        <p>
+          Information about an analysis context.
+        </p>
+        <object>
+          <field name="name">
+            <ref>String</ref>
+            <p>
+              The name of the context.
+            </p>
+          </field>
+          <field name="explicitlyAnalyzedFiles">

[Brian Wilkerson, 2015/11/05 22:43:44]

Maybe explicitFileCount and implicitFileCount? (The current names sound to me
like lists of file paths.)

[pquitslund, 2015/11/05 22:58:11]

Done.

+            <ref>int</ref>
+            <p>
+              Explicitly analyzed files.
+            </p>
+          </field>
+          <field name="implicitlyAnalyzedFiles">
+            <ref>int</ref>
+            <p>
+              Implicitly analyzed files.
+            </p>
+          </field>
+          <field name="workItemQueueLength">
+            <ref>int</ref>
+            <p>
+              The number of work items in the queue.
+            </p>
+          </field>
+          <field name="cacheEntryExceptions">
+            <list><ref>String</ref></list>
+            <p>
+              Exceptions associated with cache entries.
+            </p>
+          </field>
+        </object>
+      </type>
       <type name="Element">
         <p>
           Information about an element (something that can be declared