From 5a38b75f16ea8ba9ec95ce85a16b8dfa8382c173 Mon Sep 17 00:00:00 2001
From: epriestley <git@epriestley.com>
Date: Wed, 5 Sep 2018 10:06:47 -0700
Subject: [PATCH] In Conduit, let checkbox constraints self-document

Summary:
Ref T13195. Ref PHI851. Currently, checkbox constraints don't tell you what values are supported on the API page.

You can figure this out with "Inspect Element" or by viewing the source code, but just render a nice table instead.

Test Plan: {F5862969}

Reviewers: amckinley

Reviewed By: amckinley

Maniphest Tasks: T13195

Differential Revision: https://secure.phabricator.com/D19641
---
 src/__phutil_library_map__.php                |  2 +
 .../data/ConduitConstantDescription.php       | 26 +++++++++++
 .../PhabricatorSearchEngineAPIMethod.php      | 43 ++++++++++++++++++-
 .../PhabricatorSearchCheckboxesField.php      | 12 ++++++
 .../search/field/PhabricatorSearchField.php   |  4 ++
 5 files changed, 86 insertions(+), 1 deletion(-)
 create mode 100644 src/applications/conduit/data/ConduitConstantDescription.php

diff --git a/src/__phutil_library_map__.php b/src/__phutil_library_map__.php
index 3abc10ef49..9774741060 100644
--- a/src/__phutil_library_map__.php
+++ b/src/__phutil_library_map__.php
@@ -313,6 +313,7 @@ phutil_register_library_map(array(
     'ConduitCallTestCase' => 'applications/conduit/call/__tests__/ConduitCallTestCase.php',
     'ConduitColumnsParameterType' => 'applications/conduit/parametertype/ConduitColumnsParameterType.php',
     'ConduitConnectConduitAPIMethod' => 'applications/conduit/method/ConduitConnectConduitAPIMethod.php',
+    'ConduitConstantDescription' => 'applications/conduit/data/ConduitConstantDescription.php',
     'ConduitEpochParameterType' => 'applications/conduit/parametertype/ConduitEpochParameterType.php',
     'ConduitException' => 'applications/conduit/protocol/exception/ConduitException.php',
     'ConduitGetCapabilitiesConduitAPIMethod' => 'applications/conduit/method/ConduitGetCapabilitiesConduitAPIMethod.php',
@@ -5628,6 +5629,7 @@ phutil_register_library_map(array(
     'ConduitCallTestCase' => 'PhabricatorTestCase',
     'ConduitColumnsParameterType' => 'ConduitParameterType',
     'ConduitConnectConduitAPIMethod' => 'ConduitAPIMethod',
+    'ConduitConstantDescription' => 'Phobject',
     'ConduitEpochParameterType' => 'ConduitParameterType',
     'ConduitException' => 'Exception',
     'ConduitGetCapabilitiesConduitAPIMethod' => 'ConduitAPIMethod',
diff --git a/src/applications/conduit/data/ConduitConstantDescription.php b/src/applications/conduit/data/ConduitConstantDescription.php
new file mode 100644
index 0000000000..fe2af2b716
--- /dev/null
+++ b/src/applications/conduit/data/ConduitConstantDescription.php
@@ -0,0 +1,26 @@
+<?php
+
+final class ConduitConstantDescription extends Phobject {
+
+  private $key;
+  private $value;
+
+  public function setKey($key) {
+    $this->key = $key;
+    return $this;
+  }
+
+  public function getKey() {
+    return $this->key;
+  }
+
+  public function setValue($value) {
+    $this->value = $value;
+    return $this;
+  }
+
+  public function getValue() {
+    return $this->value;
+  }
+
+}
diff --git a/src/applications/search/engine/PhabricatorSearchEngineAPIMethod.php b/src/applications/search/engine/PhabricatorSearchEngineAPIMethod.php
index 4a8fccb876..335ba58852 100644
--- a/src/applications/search/engine/PhabricatorSearchEngineAPIMethod.php
+++ b/src/applications/search/engine/PhabricatorSearchEngineAPIMethod.php
@@ -190,15 +190,26 @@ EOTEXT
       $fields,
       array('ids', 'phids')) + $fields;
 
+    $constant_lists = array();
+
     $rows = array();
     foreach ($fields as $field) {
       $key = $field->getConduitKey();
       $label = $field->getLabel();
 
+      $constants = $field->newConduitConstants();
+
       $type_object = $field->getConduitParameterType();
       if ($type_object) {
         $type = $type_object->getTypeName();
         $description = $field->getDescription();
+        if ($constants) {
+          $description = array(
+            $description,
+            ' ',
+            phutil_tag('em', array(), pht('(See table below.)')),
+          );
+        }
       } else {
         $type = null;
         $description = phutil_tag('em', array(), pht('Not supported.'));
@@ -210,6 +221,35 @@ EOTEXT
         $type,
         $description,
       );
+
+      if ($constants) {
+        $constant_lists[] = $this->buildRemarkup(
+          pht(
+            'Constants supported by the `%s` constraint:',
+            'statuses'));
+
+        $constants_rows = array();
+        foreach ($constants as $constant) {
+          $constants_rows[] = array(
+            $constant->getKey(),
+            $constant->getValue(),
+          );
+        }
+
+        $constants_table = id(new AphrontTableView($constants_rows))
+          ->setHeaders(
+            array(
+              pht('Key'),
+              pht('Value'),
+            ))
+          ->setColumnClasses(
+            array(
+              'pre',
+              'wide',
+            ));
+
+        $constant_lists[] = $constants_table;
+      }
     }
 
     $table = id(new AphrontTableView($rows))
@@ -233,7 +273,8 @@ EOTEXT
       ->setCollapsed(true)
       ->setBackground(PHUIObjectBoxView::BLUE_PROPERTY)
       ->appendChild($this->buildRemarkup($info))
-      ->appendChild($table);
+      ->appendChild($table)
+      ->appendChild($constant_lists);
   }
 
   private function buildOrderBox(
diff --git a/src/applications/search/field/PhabricatorSearchCheckboxesField.php b/src/applications/search/field/PhabricatorSearchCheckboxesField.php
index e1a72f4576..0985c976ce 100644
--- a/src/applications/search/field/PhabricatorSearchCheckboxesField.php
+++ b/src/applications/search/field/PhabricatorSearchCheckboxesField.php
@@ -49,4 +49,16 @@ final class PhabricatorSearchCheckboxesField
     return new ConduitStringListParameterType();
   }
 
+  public function newConduitConstants() {
+    $list = array();
+
+    foreach ($this->getOptions() as $key => $option) {
+      $list[] = id(new ConduitConstantDescription())
+        ->setKey($key)
+        ->setValue($option);
+    }
+
+    return $list;
+  }
+
 }
diff --git a/src/applications/search/field/PhabricatorSearchField.php b/src/applications/search/field/PhabricatorSearchField.php
index 1a038ec665..36db0523b7 100644
--- a/src/applications/search/field/PhabricatorSearchField.php
+++ b/src/applications/search/field/PhabricatorSearchField.php
@@ -382,6 +382,10 @@ abstract class PhabricatorSearchField extends Phobject {
     return $this->enableForConduit;
   }
 
+  public function newConduitConstants() {
+    return array();
+  }
+
 
 /* -(  Utility Methods )----------------------------------------------------- */