Flesh out Conduit types for Paste search fields

Summary: Ref T9964. This fills in types and descriptions for ApplicationSearch fields in Paste.

Test Plan:
Got this nice table now:

{F1023999}

Reviewers: chad

Reviewed By: chad

Maniphest Tasks: T9964

Differential Revision: https://secure.phabricator.com/D14765

src/__phutil_library_map__.php

@@ -228,6 +228,7 @@ phutil_register_library_map(array(
     'ConduitConnectConduitAPIMethod' => 'applications/conduit/method/ConduitConnectConduitAPIMethod.php',
     'ConduitConnectionGarbageCollector' => 'applications/conduit/garbagecollector/ConduitConnectionGarbageCollector.php',
     'ConduitDeprecatedCallSetupCheck' => 'applications/conduit/check/ConduitDeprecatedCallSetupCheck.php',
+    'ConduitEpochParameterType' => 'applications/conduit/parametertype/ConduitEpochParameterType.php',
     'ConduitException' => 'applications/conduit/protocol/exception/ConduitException.php',
     'ConduitGetCapabilitiesConduitAPIMethod' => 'applications/conduit/method/ConduitGetCapabilitiesConduitAPIMethod.php',
     'ConduitGetCertificateConduitAPIMethod' => 'applications/conduit/method/ConduitGetCertificateConduitAPIMethod.php',
@@ -235,8 +236,10 @@ phutil_register_library_map(array(
     'ConduitLogGarbageCollector' => 'applications/conduit/garbagecollector/ConduitLogGarbageCollector.php',
     'ConduitMethodDoesNotExistException' => 'applications/conduit/protocol/exception/ConduitMethodDoesNotExistException.php',
     'ConduitMethodNotFoundException' => 'applications/conduit/protocol/exception/ConduitMethodNotFoundException.php',
+    'ConduitPHIDListParameterType' => 'applications/conduit/parametertype/ConduitPHIDListParameterType.php',
     'ConduitParameterType' => 'applications/conduit/parametertype/ConduitParameterType.php',
     'ConduitPingConduitAPIMethod' => 'applications/conduit/method/ConduitPingConduitAPIMethod.php',
+    'ConduitProjectListParameterType' => 'applications/conduit/parametertype/ConduitProjectListParameterType.php',
     'ConduitQueryConduitAPIMethod' => 'applications/conduit/method/ConduitQueryConduitAPIMethod.php',
     'ConduitResultSearchEngineExtension' => 'applications/conduit/query/ConduitResultSearchEngineExtension.php',
     'ConduitSSHWorkflow' => 'applications/conduit/ssh/ConduitSSHWorkflow.php',
@@ -4074,6 +4077,7 @@ phutil_register_library_map(array(
     'ConduitConnectConduitAPIMethod' => 'ConduitAPIMethod',
     'ConduitConnectionGarbageCollector' => 'PhabricatorGarbageCollector',
     'ConduitDeprecatedCallSetupCheck' => 'PhabricatorSetupCheck',
+    'ConduitEpochParameterType' => 'ConduitListParameterType',
     'ConduitException' => 'Exception',
     'ConduitGetCapabilitiesConduitAPIMethod' => 'ConduitAPIMethod',
     'ConduitGetCertificateConduitAPIMethod' => 'ConduitAPIMethod',
@@ -4081,8 +4085,10 @@ phutil_register_library_map(array(
     'ConduitLogGarbageCollector' => 'PhabricatorGarbageCollector',
     'ConduitMethodDoesNotExistException' => 'ConduitMethodNotFoundException',
     'ConduitMethodNotFoundException' => 'ConduitException',
+    'ConduitPHIDListParameterType' => 'ConduitListParameterType',
     'ConduitParameterType' => 'Phobject',
     'ConduitPingConduitAPIMethod' => 'ConduitAPIMethod',
+    'ConduitProjectListParameterType' => 'ConduitListParameterType',
     'ConduitQueryConduitAPIMethod' => 'ConduitAPIMethod',
     'ConduitResultSearchEngineExtension' => 'PhabricatorSearchEngineExtension',
     'ConduitSSHWorkflow' => 'PhabricatorSSHWorkflow',

src/applications/conduit/parametertype/ConduitEpochParameterType.php

@@ -0,0 +1,37 @@
+<?php
+
+final class ConduitEpochParameterType
+  extends ConduitListParameterType {
+
+  protected function getParameterValue(array $request, $key) {
+    $value = parent::getParameterValue($request, $key);
+
+    if (!is_int($value)) {
+      $this->raiseValidationException(
+        $request,
+        $key,
+        pht('Expected integer, got something else.'));
+    }
+
+    return $value;
+  }
+
+  protected function getParameterTypeName() {
+    return 'epoch';
+  }
+
+  protected function getParameterFormatDescriptions() {
+    return array(
+      pht('Epoch timestamp, as an integer.'),
+    );
+  }
+
+  protected function getParameterExamples() {
+    return array(
+      '["PHID-PROJ-1111"]',
+      '["backend"]',
+      '["PHID-PROJ-2222", "frontend"]',
+    );
+  }
+
+}

src/applications/conduit/parametertype/ConduitListParameterType.php

@@ -4,7 +4,7 @@ abstract class ConduitListParameterType
   extends ConduitParameterType {
 
   protected function getParameterValue(array $request, $key) {
-    $value = parent::getParameterValue();
+    $value = parent::getParameterValue($request, $key);
 
     if (!is_array($value)) {
       $this->raiseValidationException(
@@ -30,6 +30,22 @@ abstract class ConduitListParameterType
     return $value;
   }
 
+  protected function validateStringList(array $request, $key, array $list) {
+    foreach ($list as $idx => $item) {
+      if (!is_string($item)) {
+        $this->raiseValidationException(
+          $request,
+          $key,
+          pht(
+            'Expected a list of strings, but item with index "%s" is '.
+            'not a string.',
+            $idx));
+      }
+    }
+
+    return $list;
+  }
+
   protected function getParameterDefault() {
     return array();
   }

src/applications/conduit/parametertype/ConduitPHIDListParameterType.php

@@ -0,0 +1,27 @@
+<?php
+
+final class ConduitPHIDListParameterType
+  extends ConduitListParameterType {
+
+  protected function getParameterValue(array $request, $key) {
+    $list = parent::getParameterValue($request, $key);
+    return $this->validateStringList($request, $key, $list);
+  }
+
+  protected function getParameterTypeName() {
+    return 'list<phid>';
+  }
+
+  protected function getParameterFormatDescriptions() {
+    return array(
+      pht('List of PHIDs.'),
+    );
+  }
+
+  protected function getParameterExamples() {
+    return array(
+      '["PHID-WXYZ-1111", "PHID-WXYZ-2222"]',
+    );
+  }
+
+}

src/applications/conduit/parametertype/ConduitProjectListParameterType.php

@@ -0,0 +1,34 @@
+<?php
+
+final class ConduitProjectListParameterType
+  extends ConduitListParameterType {
+
+  protected function getParameterValue(array $request, $key) {
+    $list = parent::getParameterValue($request, $key);
+    $list = $this->validateStringList($request, $key, $list);
+    return id(new PhabricatorProjectPHIDResolver())
+      ->setViewer($this->getViewer())
+      ->resolvePHIDs($list);
+  }
+
+  protected function getParameterTypeName() {
+    return 'list<project>';
+  }
+
+  protected function getParameterFormatDescriptions() {
+    return array(
+      pht('List of project PHIDs.'),
+      pht('List of project tags.'),
+      pht('List with a mixture of PHIDs and tags.'),
+    );
+  }
+
+  protected function getParameterExamples() {
+    return array(
+      '["PHID-PROJ-1111"]',
+      '["backend"]',
+      '["PHID-PROJ-2222", "frontend"]',
+    );
+  }
+
+}

src/applications/conduit/parametertype/ConduitStringListParameterType.php

@@ -4,21 +4,8 @@ final class ConduitStringListParameterType
   extends ConduitListParameterType {
 
   protected function getParameterValue(array $request, $key) {
-    $list = parent::getParameterValue();
+    $list = parent::getParameterValue($request, $key);
-
+    return $this->validateStringList($request, $key, $list);
-    foreach ($list as $idx => $item) {
-      if (!is_string($item)) {
-        $this->raiseValidationException(
-          $request,
-          $key,
-          pht(
-            'Expected a list of strings, but item with index "%s" is '.
-            'not a string.',
-            $idx));
-      }
-    }
-
-    return $list;
   }
 
   protected function getParameterTypeName() {

src/applications/conduit/parametertype/ConduitUserListParameterType.php

@@ -4,7 +4,8 @@ final class ConduitUserListParameterType
   extends ConduitListParameterType {
 
   protected function getParameterValue(array $request, $key) {
-    $list = parent::getParameterValue();
+    $list = parent::getParameterValue($request, $key);
+    $list = $this->validateStringList($request, $key, $list);
     return id(new PhabricatorUserPHIDResolver())
       ->setViewer($this->getViewer())
       ->resolvePHIDs($list);

src/applications/paste/query/PhabricatorPasteSearchEngine.php

@@ -48,19 +48,29 @@ final class PhabricatorPasteSearchEngine
         ->setAliases(array('authors'))
         ->setKey('authorPHIDs')
         ->setConduitKey('authors')
-        ->setLabel(pht('Authors')),
+        ->setLabel(pht('Authors'))
+        ->setDescription(
+          pht('Search for pastes with specific authors.')),
       id(new PhabricatorSearchStringListField())
         ->setKey('languages')
-        ->setLabel(pht('Languages')),
+        ->setLabel(pht('Languages'))
+        ->setDescription(
+          pht('Search for pastes highlighted in specific languages.')),
       id(new PhabricatorSearchDateField())
         ->setKey('createdStart')
-        ->setLabel(pht('Created After')),
+        ->setLabel(pht('Created After'))
+        ->setDescription(
+          pht('Search for pastes created after a given time.')),
       id(new PhabricatorSearchDateField())
         ->setKey('createdEnd')
-        ->setLabel(pht('Created Before')),
+        ->setLabel(pht('Created Before'))
+        ->setDescription(
+          pht('Search for pastes created before a given time.')),
       id(new PhabricatorSearchCheckboxesField())
         ->setKey('statuses')
         ->setLabel(pht('Status'))
+        ->setDescription(
+          pht('Search for archived or active pastes.'))
         ->setOptions(
           id(new PhabricatorPaste())
             ->getStatusNameMap()),

src/applications/project/engineextension/PhabricatorProjectsSearchEngineExtension.php

@@ -42,7 +42,9 @@ final class PhabricatorProjectsSearchEngineExtension
       ->setKey('projectPHIDs')
       ->setConduitKey('projects')
       ->setAliases(array('project', 'projects'))
-      ->setLabel(pht('Projects'));
+      ->setLabel(pht('Projects'))
+      ->setDescription(
+        pht('Search for objects associated with given projects.'));
 
     return $fields;
   }

src/applications/project/searchfield/PhabricatorProjectSearchField.php

@@ -47,4 +47,8 @@ final class PhabricatorProjectSearchField
 
   }
 
+  protected function newConduitParameterType() {
+    return new ConduitProjectListParameterType();
+  }
+
 }

src/applications/search/engine/PhabricatorSearchEngineAPIMethod.php

@@ -160,8 +160,7 @@ EOTEXT
       $type_object = $field->getConduitParameterType();
       if ($type_object) {
         $type = '`'.$type_object->getTypeName().'`';
-        // TODO: Support generating and surfacing this information.
+        $description = $field->getDescription();
-        $description = pht('TODO');
       } else {
         $type = '';
         $description = '//'.pht('Not Supported').'//';

src/applications/search/field/PhabricatorSearchDateField.php

@@ -38,4 +38,8 @@ final class PhabricatorSearchDateField
     return PhabricatorTime::parseLocalTime($value, $this->getViewer());
   }
 
+  protected function newConduitParameterType() {
+    return new ConduitEpochParameterType();
+  }
+
 }

src/applications/search/field/PhabricatorSearchField.php

@@ -16,6 +16,7 @@ abstract class PhabricatorSearchField extends Phobject {
   private $label;
   private $aliases = array();
   private $errors = array();
+  private $description;
 
 
 /* -(  Configuring Fields  )------------------------------------------------- */
@@ -163,6 +164,30 @@ abstract class PhabricatorSearchField extends Phobject {
   }
 
 
+  /**
+   * Set a human-readable description for this field.
+   *
+   * @param string Human-readable description.
+   * @return this
+   * @task config
+   */
+  public function setDescription($description) {
+    $this->description = $description;
+    return $this;
+  }
+
+
+  /**
+   * Get this field's human-readable description.
+   *
+   * @return string|null Human-readable description.
+   * @task config
+   */
+  public function getDescription() {
+    return $this->description;
+  }
+
+
 /* -(  Handling Errors  )---------------------------------------------------- */
 
 

src/applications/search/field/PhabricatorSearchSubscribersField.php

@@ -18,4 +18,10 @@ final class PhabricatorSearchSubscribersField
     return new PhabricatorMetaMTAMailableFunctionDatasource();
   }
 
+  protected function newConduitParameterType() {
+    // TODO: Ideally, this should eventually be a "Subscribers" type which
+    // accepts projects as well.
+    return new ConduitUserListParameterType();
+  }
+
 }

src/applications/spaces/engineextension/PhabricatorSpacesSearchEngineExtension.php

@@ -30,7 +30,9 @@ final class PhabricatorSpacesSearchEngineExtension
         ->setKey('spacePHIDs')
         ->setConduitKey('spaces')
         ->setAliases(array('space', 'spaces'))
-        ->setLabel(pht('Spaces'));
+        ->setLabel(pht('Spaces'))
+        ->setDescription(
+          pht('Search for objects in certain spaces.'));
     }
 
     return $fields;

src/applications/spaces/searchfield/PhabricatorSpacesSearchField.php

@@ -40,4 +40,8 @@ final class PhabricatorSpacesSearchField
     return $phids;
   }
 
+  protected function newConduitParameterType() {
+    return new ConduitPHIDListParameterType();
+  }
+
 }

src/applications/subscriptions/engineextension/PhabricatorSubscriptionsSearchEngineExtension.php

@@ -43,7 +43,9 @@ final class PhabricatorSubscriptionsSearchEngineExtension
       ->setLabel(pht('Subscribers'))
       ->setKey('subscriberPHIDs')
       ->setConduitKey('subscribers')
-      ->setAliases(array('subscriber', 'subscribers'));
+      ->setAliases(array('subscriber', 'subscribers'))
+      ->setDescription(
+        pht('Search for objects with certain subscribers.'));
 
     return $fields;
   }