1
0
Fork 0
mirror of https://we.phorge.it/source/phorge.git synced 2024-11-14 10:52:41 +01:00

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
This commit is contained in:
epriestley 2019-02-25 07:10:29 -08:00
parent 83aba7b01c
commit d1546209c5
3 changed files with 72 additions and 28 deletions

View file

@ -409,4 +409,19 @@ abstract class ConduitAPIMethod
$capability); $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);
}
} }

View file

@ -144,7 +144,7 @@ EOTEXT
->setHeaderText(pht('Builtin and Saved Queries')) ->setHeaderText(pht('Builtin and Saved Queries'))
->setCollapsed(true) ->setCollapsed(true)
->setBackground(PHUIObjectBoxView::BLUE_PROPERTY) ->setBackground(PHUIObjectBoxView::BLUE_PROPERTY)
->appendChild($this->buildRemarkup($info)) ->appendChild($this->newRemarkupDocumentationView($info))
->appendChild($table); ->appendChild($table);
} }
@ -223,7 +223,7 @@ EOTEXT
); );
if ($constants) { if ($constants) {
$constant_lists[] = $this->buildRemarkup( $constant_lists[] = $this->newRemarkupDocumentationView(
pht( pht(
'Constants supported by the `%s` constraint:', 'Constants supported by the `%s` constraint:',
'statuses')); 'statuses'));
@ -283,7 +283,7 @@ EOTEXT
->setHeaderText(pht('Custom Query Constraints')) ->setHeaderText(pht('Custom Query Constraints'))
->setCollapsed(true) ->setCollapsed(true)
->setBackground(PHUIObjectBoxView::BLUE_PROPERTY) ->setBackground(PHUIObjectBoxView::BLUE_PROPERTY)
->appendChild($this->buildRemarkup($info)) ->appendChild($this->newRemarkupDocumentationView($info))
->appendChild($table) ->appendChild($table)
->appendChild($constant_lists); ->appendChild($constant_lists);
} }
@ -391,9 +391,9 @@ EOTEXT
->setHeaderText(pht('Result Ordering')) ->setHeaderText(pht('Result Ordering'))
->setCollapsed(true) ->setCollapsed(true)
->setBackground(PHUIObjectBoxView::BLUE_PROPERTY) ->setBackground(PHUIObjectBoxView::BLUE_PROPERTY)
->appendChild($this->buildRemarkup($orders_info)) ->appendChild($this->newRemarkupDocumentationView($orders_info))
->appendChild($orders_table) ->appendChild($orders_table)
->appendChild($this->buildRemarkup($columns_info)) ->appendChild($this->newRemarkupDocumentationView($columns_info))
->appendChild($columns_table); ->appendChild($columns_table);
} }
@ -472,7 +472,7 @@ EOTEXT
->setHeaderText(pht('Object Fields')) ->setHeaderText(pht('Object Fields'))
->setCollapsed(true) ->setCollapsed(true)
->setBackground(PHUIObjectBoxView::BLUE_PROPERTY) ->setBackground(PHUIObjectBoxView::BLUE_PROPERTY)
->appendChild($this->buildRemarkup($info)) ->appendChild($this->newRemarkupDocumentationView($info))
->appendChild($table); ->appendChild($table);
} }
@ -562,7 +562,7 @@ EOTEXT
->setHeaderText(pht('Attachments')) ->setHeaderText(pht('Attachments'))
->setCollapsed(true) ->setCollapsed(true)
->setBackground(PHUIObjectBoxView::BLUE_PROPERTY) ->setBackground(PHUIObjectBoxView::BLUE_PROPERTY)
->appendChild($this->buildRemarkup($info)) ->appendChild($this->newRemarkupDocumentationView($info))
->appendChild($table); ->appendChild($table);
} }
@ -633,21 +633,7 @@ EOTEXT
->setHeaderText(pht('Paging and Limits')) ->setHeaderText(pht('Paging and Limits'))
->setCollapsed(true) ->setCollapsed(true)
->setBackground(PHUIObjectBoxView::BLUE_PROPERTY) ->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);
}
} }

View file

@ -8,15 +8,58 @@ final class TransactionSearchConduitAPIMethod
} }
public function getMethodDescription() { public function getMethodDescription() {
return pht('Read transactions for an object.'); return pht('Read transactions and comments for an object.');
} }
public function getMethodStatus() { public function getMethodDocumentation() {
return self::METHOD_STATUS_UNSTABLE; $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() { One common reason to call this method is that you're implmenting a webhook and
return pht('This method is new and experimental.'); 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() { protected function defineParamTypes() {