From d1546209c53613163baa72912ad02fa92a683626 Mon Sep 17 00:00:00 2001
From: epriestley <git@epriestley.com>
Date: Mon, 25 Feb 2019 07:10:29 -0800
Subject: [PATCH] Expand documentation for "transaction.search"

Summary: Depends on D20209. Ref T13255. It would probably be nice to make this into a "real" `*.search` API method some day, but at least document the features for now.

Test Plan: Read documentation.

Reviewers: amckinley

Reviewed By: amckinley

Maniphest Tasks: T13255

Differential Revision: https://secure.phabricator.com/D20211
---
 .../conduit/method/ConduitAPIMethod.php       | 15 +++++
 .../PhabricatorSearchEngineAPIMethod.php      | 30 +++-------
 .../TransactionSearchConduitAPIMethod.php     | 55 +++++++++++++++++--
 3 files changed, 72 insertions(+), 28 deletions(-)

diff --git a/src/applications/conduit/method/ConduitAPIMethod.php b/src/applications/conduit/method/ConduitAPIMethod.php
index 05831a782d..0fbfaa2fc3 100644
--- a/src/applications/conduit/method/ConduitAPIMethod.php
+++ b/src/applications/conduit/method/ConduitAPIMethod.php
@@ -409,4 +409,19 @@ abstract class ConduitAPIMethod
       $capability);
   }
 
+  final protected function newRemarkupDocumentationView($remarkup) {
+    $viewer = $this->getViewer();
+
+    $view = new PHUIRemarkupView($viewer, $remarkup);
+
+    $view->setRemarkupOptions(
+      array(
+        PHUIRemarkupView::OPTION_PRESERVE_LINEBREAKS => false,
+      ));
+
+    return id(new PHUIBoxView())
+      ->appendChild($view)
+      ->addPadding(PHUI::PADDING_LARGE);
+  }
+
 }
diff --git a/src/applications/search/engine/PhabricatorSearchEngineAPIMethod.php b/src/applications/search/engine/PhabricatorSearchEngineAPIMethod.php
index 235d74d6f3..510ad91864 100644
--- a/src/applications/search/engine/PhabricatorSearchEngineAPIMethod.php
+++ b/src/applications/search/engine/PhabricatorSearchEngineAPIMethod.php
@@ -144,7 +144,7 @@ EOTEXT
       ->setHeaderText(pht('Builtin and Saved Queries'))
       ->setCollapsed(true)
       ->setBackground(PHUIObjectBoxView::BLUE_PROPERTY)
-      ->appendChild($this->buildRemarkup($info))
+      ->appendChild($this->newRemarkupDocumentationView($info))
       ->appendChild($table);
   }
 
@@ -223,7 +223,7 @@ EOTEXT
       );
 
       if ($constants) {
-        $constant_lists[] = $this->buildRemarkup(
+        $constant_lists[] = $this->newRemarkupDocumentationView(
           pht(
             'Constants supported by the `%s` constraint:',
             'statuses'));
@@ -283,7 +283,7 @@ EOTEXT
       ->setHeaderText(pht('Custom Query Constraints'))
       ->setCollapsed(true)
       ->setBackground(PHUIObjectBoxView::BLUE_PROPERTY)
-      ->appendChild($this->buildRemarkup($info))
+      ->appendChild($this->newRemarkupDocumentationView($info))
       ->appendChild($table)
       ->appendChild($constant_lists);
   }
@@ -391,9 +391,9 @@ EOTEXT
       ->setHeaderText(pht('Result Ordering'))
       ->setCollapsed(true)
       ->setBackground(PHUIObjectBoxView::BLUE_PROPERTY)
-      ->appendChild($this->buildRemarkup($orders_info))
+      ->appendChild($this->newRemarkupDocumentationView($orders_info))
       ->appendChild($orders_table)
-      ->appendChild($this->buildRemarkup($columns_info))
+      ->appendChild($this->newRemarkupDocumentationView($columns_info))
       ->appendChild($columns_table);
   }
 
@@ -472,7 +472,7 @@ EOTEXT
       ->setHeaderText(pht('Object Fields'))
       ->setCollapsed(true)
       ->setBackground(PHUIObjectBoxView::BLUE_PROPERTY)
-      ->appendChild($this->buildRemarkup($info))
+      ->appendChild($this->newRemarkupDocumentationView($info))
       ->appendChild($table);
   }
 
@@ -562,7 +562,7 @@ EOTEXT
       ->setHeaderText(pht('Attachments'))
       ->setCollapsed(true)
       ->setBackground(PHUIObjectBoxView::BLUE_PROPERTY)
-      ->appendChild($this->buildRemarkup($info))
+      ->appendChild($this->newRemarkupDocumentationView($info))
       ->appendChild($table);
   }
 
@@ -633,21 +633,7 @@ EOTEXT
       ->setHeaderText(pht('Paging and Limits'))
       ->setCollapsed(true)
       ->setBackground(PHUIObjectBoxView::BLUE_PROPERTY)
-      ->appendChild($this->buildRemarkup($info));
+      ->appendChild($this->newRemarkupDocumentationView($info));
   }
 
-  private function buildRemarkup($remarkup) {
-    $viewer = $this->getViewer();
-
-    $view = new PHUIRemarkupView($viewer, $remarkup);
-
-    $view->setRemarkupOptions(
-      array(
-        PHUIRemarkupView::OPTION_PRESERVE_LINEBREAKS => false,
-      ));
-
-    return id(new PHUIBoxView())
-      ->appendChild($view)
-      ->addPadding(PHUI::PADDING_LARGE);
-  }
 }
diff --git a/src/applications/transactions/conduit/TransactionSearchConduitAPIMethod.php b/src/applications/transactions/conduit/TransactionSearchConduitAPIMethod.php
index 362b490a42..4ab5de519e 100644
--- a/src/applications/transactions/conduit/TransactionSearchConduitAPIMethod.php
+++ b/src/applications/transactions/conduit/TransactionSearchConduitAPIMethod.php
@@ -8,15 +8,58 @@ final class TransactionSearchConduitAPIMethod
   }
 
   public function getMethodDescription() {
-    return pht('Read transactions for an object.');
+    return pht('Read transactions and comments for an object.');
   }
 
-  public function getMethodStatus() {
-    return self::METHOD_STATUS_UNSTABLE;
-  }
+  public function getMethodDocumentation() {
+    $markup = pht(<<<EOREMARKUP
+When an object (like a task) is edited, Phabricator creates a "transaction"
+and applies it. This list of transactions on each object is the basis for
+essentially all edits and comments in Phabricator. Reviewing the transaction
+record allows you to see who edited an object, when, and how their edit changed
+things.
 
-  public function getMethodStatusDescription() {
-    return pht('This method is new and experimental.');
+One common reason to call this method is that you're implmenting a webhook and
+just received a notification that an object has changed. See the Webhooks
+documentation for more detailed discussion of this use case.
+
+Constraints
+===========
+
+These constraints are supported:
+
+  - `phids` //Optional list<phid>.// Find specific transactions by PHID. This
+    is most likely to be useful if you're responding to a webhook notification
+    and want to inspect only the related events.
+  - `authorPHIDs` //Optional list<phid>.// Find transactions with particular
+    authors.
+
+Transaction Format
+==================
+
+Each transaction has custom data describing what the transaction did. The
+format varies from transaction to transaction. The easiest way to figure out
+exactly what a particular transaction looks like is to make the associated kind
+of edit to a test object, then query that object.
+
+Not all transactions have data: by default, transactions have a `null` "type"
+and no additional data. This API does not expose raw transaction data because
+some of it is internal, oddly named, misspelled, confusing, not useful, or
+could create security or policy problems to expose directly.
+
+New transactions are exposed (with correctly spelled, comprehensible types and
+useful, reasonable fields) as we become aware of use cases for them.
+
+EOREMARKUP
+      );
+
+    $markup = $this->newRemarkupDocumentationView($markup);
+
+    return id(new PHUIObjectBoxView())
+      ->setCollapsed(true)
+      ->setBackground(PHUIObjectBoxView::BLUE_PROPERTY)
+      ->setHeaderText(pht('Method Details'))
+      ->appendChild($markup);
   }
 
   protected function defineParamTypes() {