Add some documentation about how to set paths with owners.edit

Summary:
Ref T9964.

  - New mechanism for rich documentation on unusual/complicated edits.
  - Add some docs to `paths.set` since it's not self-evident what you're supposed to pass in.

Test Plan: {F1027177}

Reviewers: chad

Reviewed By: chad

Maniphest Tasks: T9964

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

src/applications/owners/editor/PhabricatorOwnersPackageEditEngine.php

@@ -44,6 +44,35 @@ final class PhabricatorOwnersPackageEditEngine
   }
 
   protected function buildCustomEditFields($object) {
+
+    $paths_help = pht(<<<EOTEXT
+When updating the paths for a package, pass a list of dictionaries like
+this as the `value` for the transaction:
+
+```lang=json, name="Example Paths Value"
+[
+  {
+    "repositoryPHID": "PHID-REPO-1234",
+    "path": "/path/to/directory/",
+    "excluded": false
+  },
+  {
+    "repositoryPHID": "PHID-REPO-1234",
+    "path": "/another/example/path/",
+    "excluded": false
+  }
+]
+```
+
+This transaction will set the paths to the list you provide, overwriting any
+previous paths.
+
+Generally, you will call `owners.search` first to get a list of current paths
+(which are provided in the same format), make changes, then update them by
+applying a transaction of this type.
+EOTEXT
+      );
+
     return array(
       id(new PhabricatorTextEditField())
         ->setKey('name')
@@ -95,7 +124,8 @@ final class PhabricatorOwnersPackageEditEngine
         ->setLabel(pht('Paths'))
         ->setDescription(pht('Set paths for this package.'))
         ->setIsConduitOnly(true)
-        ->setTransactionType(PhabricatorOwnersPackageTransaction::TYPE_PATHS),
+        ->setTransactionType(PhabricatorOwnersPackageTransaction::TYPE_PATHS)
+        ->setConduitDocumentation($paths_help),
     );
   }
 

src/applications/transactions/editengine/PhabricatorEditEngineAPIMethod.php

@@ -173,6 +173,12 @@ EOTEXT
         $type->getTransactionType());
       $section[] = null;
 
+      $type_documentation = $type->getConduitDocumentation();
+      if ($type_documentation) {
+        $section[] = $type_documentation;
+        $section[] = null;
+      }
+
       $type_description = pht(
         'Use `%s` to select this edit type.',
         $type->getEditType());

src/applications/transactions/editfield/PhabricatorEditField.php

@@ -15,6 +15,7 @@ abstract class PhabricatorEditField extends Phobject {
   private $description;
   private $editTypeKey;
   private $isRequired;
+  private $conduitDocumentation;
 
   private $commentActionLabel;
   private $commentActionValue;
@@ -553,7 +554,8 @@ abstract class PhabricatorEditField extends Phobject {
       ->setEditType($type_key)
       ->setTransactionType($transaction_type)
       ->setDescription($this->getDescription())
-      ->setMetadata($this->getMetadata());
+      ->setMetadata($this->getMetadata())
+      ->setConduitDocumentation($this->getConduitDocumentation());
   }
 
   public function getConduitEditTypes() {
@@ -677,4 +679,13 @@ abstract class PhabricatorEditField extends Phobject {
     return $edit_type->generateTransactions($template, $spec);
   }
 
+  public function setConduitDocumentation($conduit_documentation) {
+    $this->conduitDocumentation = $conduit_documentation;
+    return $this;
+  }
+
+  public function getConduitDocumentation() {
+    return $this->conduitDocumentation;
+  }
+
 }

src/applications/transactions/edittype/PhabricatorEditType.php

@@ -9,6 +9,7 @@ abstract class PhabricatorEditType extends Phobject {
   private $description;
   private $summary;
   private $metadata = array();
+  private $conduitDocumentation;
 
   public function setDescription($description) {
     $this->description = $description;
@@ -58,6 +59,15 @@ abstract class PhabricatorEditType extends Phobject {
     return $this->editType;
   }
 
+  public function setConduitDocumentation($conduit_documentation) {
+    $this->conduitDocumentation = $conduit_documentation;
+    return $this;
+  }
+
+  public function getConduitDocumentation() {
+    return $this->conduitDocumentation;
+  }
+
   public function setMetadata($metadata) {
     $this->metadata = $metadata;
     return $this;