Improve some documentation for "diffusion.commit.search"

Summary:
Ref T13195. See PHI851. Start by making some minor improvements here:

  - Clarify that the example of what constraints look like is just an example.
  - Add descriptions for parameters missing descriptions.

Test Plan: Looked at API method page, saw more helpful/complete instructions.

Reviewers: amckinley

Reviewed By: amckinley

Maniphest Tasks: T13195

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

src/applications/audit/query/PhabricatorCommitSearchEngine.php

@@ -67,35 +67,48 @@ final class PhabricatorCommitSearchEngine
         ->setKey('responsiblePHIDs')
         ->setConduitKey('responsible')
         ->setAliases(array('responsible', 'responsibles', 'responsiblePHID'))
-        ->setDatasource(new DifferentialResponsibleDatasource()),
+        ->setDatasource(new DifferentialResponsibleDatasource())
+        ->setDescription(
+          pht(
+            'Find commits where given users, projects, or packages are '.
+            'responsible for the next steps in the audit workflow.')),
       id(new PhabricatorUsersSearchField())
         ->setLabel(pht('Authors'))
         ->setKey('authorPHIDs')
         ->setConduitKey('authors')
-        ->setAliases(array('author', 'authors', 'authorPHID')),
+        ->setAliases(array('author', 'authors', 'authorPHID'))
+        ->setDescription(pht('Find commits authored by particular users.')),
       id(new PhabricatorSearchDatasourceField())
         ->setLabel(pht('Auditors'))
         ->setKey('auditorPHIDs')
         ->setConduitKey('auditors')
         ->setAliases(array('auditor', 'auditors', 'auditorPHID'))
-        ->setDatasource(new DiffusionAuditorFunctionDatasource()),
+        ->setDatasource(new DiffusionAuditorFunctionDatasource())
+        ->setDescription(
+          pht(
+            'Find commits where given users, projects, or packages are '.
+            'auditors.')),
       id(new PhabricatorSearchCheckboxesField())
         ->setLabel(pht('Audit Status'))
         ->setKey('statuses')
         ->setAliases(array('status'))
-        ->setOptions(PhabricatorAuditCommitStatusConstants::getStatusNameMap()),
+        ->setOptions(PhabricatorAuditCommitStatusConstants::getStatusNameMap())
+        ->setDescription(pht('Find commits with given audit statuses.')),
       id(new PhabricatorSearchDatasourceField())
         ->setLabel(pht('Repositories'))
         ->setKey('repositoryPHIDs')
         ->setConduitKey('repositories')
         ->setAliases(array('repository', 'repositories', 'repositoryPHID'))
-        ->setDatasource(new DiffusionRepositoryFunctionDatasource()),
+        ->setDatasource(new DiffusionRepositoryFunctionDatasource())
+        ->setDescription(pht('Find commits in particular repositories.')),
       id(new PhabricatorSearchDatasourceField())
         ->setLabel(pht('Packages'))
         ->setKey('packagePHIDs')
         ->setConduitKey('packages')
         ->setAliases(array('package', 'packages', 'packagePHID'))
-        ->setDatasource(new PhabricatorOwnersPackageDatasource()),
+        ->setDatasource(new PhabricatorOwnersPackageDatasource())
+        ->setDescription(
+          pht('Find commits which affect given packages.')),
       id(new PhabricatorSearchThreeStateField())
         ->setLabel(pht('Unreachable'))
         ->setKey('unreachable')

src/applications/search/engine/PhabricatorSearchEngineAPIMethod.php

@@ -161,7 +161,9 @@ If you specify both a `queryKey` and `constraints`, the builtin or saved query
 will be applied first as a starting point, then any additional values in
 `constraints` will be applied, overwriting the defaults from the original query.
 
-Specify constraints like this:
+Different endpoints support different constraints. The constraints this method
+supports are detailed below. As an example, you might specify constraints like
+this:
 
 ```lang=json, name="Example Custom Constraints"
 {