Proposal for RefactoringMethodParameter.

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 1f307600c7fac2cc7f0526b899a296dad8037915..7cfcebccef3e93f353b5b00898566f3fe459ed0d 100644
--- a/pkg/analysis_server/tool/spec/spec_input.html
+++ b/pkg/analysis_server/tool/spec/spec_input.html
@@ -2418,25 +2418,6 @@
           </field>
         </object>
       </type>
-      <type name="Parameter">
-        <p>
-          A description of a parameter.
-        </p>
-        <object>
-          <field name="type">
-            <ref>String</ref>
-            <p>
-              The type that should be given to the parameter.
-            </p>
-          </field>
-          <field name="name">
-            <ref>String</ref>
-            <p>
-              The name that should be given to the parameter.
-            </p>
-          </field>
-        </object>
-      </type>
       <type name="Position">
         <p>
           A position within a file.
@@ -2471,6 +2452,58 @@
           <value><code>RENAME</code></value>
         </enum>
       </type>
+      <type name="RefactoringMethodParameter">
+        <p>
+          A description of a parameter in a method refactoring.
+        </p>
+        <object>
+          <field name="id" optional="true">
+            <ref>String</ref>
+            <p>
+              The unique identifier of the parameter.
+              Clients may omit this field for the parameters they want to add.
+            </p>
+          </field>
+          <field name="kind">
+            <ref>RefactoringMethodParameterKind</ref>
+            <p>
+              The type that should be given to the parameter, or the return type
+              of the parameter's function type.
+            </p>
+          </field>
+          <field name="type">
+            <ref>String</ref>
+            <p>
+              The kind of the parameter.

[Brian Wilkerson, 2014/08/14 14:38:08]

I think the comments for "kind" and "type" got reversed.

[scheglov, 2014/08/14 15:54:40]

Ouch!
Fixed.

+            </p>
+          </field>
+          <field name="name">
+            <ref>String</ref>
+            <p>
+              The name that should be given to the parameter.
+            </p>
+          </field>
+          <field name="parameters" optional="true">
+            <ref>String</ref>

[Brian Wilkerson, 2014/08/14 14:38:08]

Do we want this to be List<RefactoringMethodParameter>, or is that overkill?

[scheglov, 2014/08/14 15:54:40]

We're not going to change them, so we don't need to make it a list.
As I can see it, both "Extract Method" and "Change Method/Function Signature"
will work only with "top-level" parameters.

In the future we could add a separate refactoring, like "Change Parameter
Function Signature".
Maybe even using the same "Change Function Signature" UI (action, dialog), but
with a quite different implementation.

+            <p>
+              The parameter list of the parameter's function type.
+              If the parameter is not of a function type, this field will
+              not be defined. If the function type has zero parameters, this
+              field will have a value of "()".
+            </p>
+          </field>
+        </object>
+      </type>
+      <type name="RefactoringMethodParameterKind">
+        <p>
+          An enumeration of the kinds of parameters.
+        </p>
+        <enum>
+          <value><code>REQUIRED</code></value>
+          <value><code>POSITIONAL</code></value>
+          <value><code>NAMED</code></value>
+        </enum>
+      </type>
       <type name="RefactoringProblem">
         <p>
           A description of a problem related to a refactoring.
@@ -2897,7 +2930,7 @@
             </p>
           </field>
           <field name="parameters">
-            <list><ref>Parameter</ref></list>
+            <list><ref>RefactoringMethodParameter</ref></list>
             <p>
               The proposed parameters for the method.
             </p>
@@ -2949,9 +2982,21 @@
             </p>
           </field>
           <field name="parameters">
-            <list><ref>Parameter</ref></list>
+            <list><ref>RefactoringMethodParameter</ref></list>
             <p>
               The parameters that should be defined for the method.
+              <p>
+                Only trailing parameters may be of POSITIONAL or NAMED kinds.
+                All the trailing parameters must use the same kind.

[Brian Wilkerson, 2014/08/14 14:38:08]

I think it should be defined to be an error if the parameters are not valid.

[scheglov, 2014/08/14 15:54:40]

Done.

+              </p>
+              <ul>
+                <li>
+                  To change the order and/or update proposed paramerers, add
+                  parameters with the same identifiers as proposed.
+                </li>
+                <li>To add new parameters, omit their identifier.</li>
+                <li>To remove some parameters, omit them in this list.</li>
+              </ul>
             </p>
           </field>
           <field name="extractAll">