From a36dc81715f68cdcadfd11ded4268bc5da1d7ff0 Mon Sep 17 00:00:00 2001
From: epriestley <git@epriestley.com>
Date: Wed, 27 May 2015 10:26:27 -0700
Subject: [PATCH] Provide more documentation for Arcanist upload stuff

Summary: Ref T8259. Make some highly-ambiguous methods like `setData()` more clear.

Test Plan: reading

Reviewers: btrahan

Reviewed By: btrahan

Subscribers: epriestley

Maniphest Tasks: T8259

Differential Revision: https://secure.phabricator.com/D13038
---
 src/upload/ArcanistFileDataRef.php  | 24 ++++++++++++++++++++++++
 src/upload/ArcanistFileUploader.php | 26 +++++++++++++++++++++++++-
 2 files changed, 49 insertions(+), 1 deletion(-)

diff --git a/src/upload/ArcanistFileDataRef.php b/src/upload/ArcanistFileDataRef.php
index 053c6b57..795fbd67 100644
--- a/src/upload/ArcanistFileDataRef.php
+++ b/src/upload/ArcanistFileDataRef.php
@@ -33,6 +33,13 @@ final class ArcanistFileDataRef extends Phobject {
 
 
   /**
+   * Set a human-readable display filename, like "file.jpg".
+   *
+   * This name does not correspond to a path on disk, and is purely for
+   * human consumption.
+   *
+   * @param string Filename.
+   * @return this
    * @task config
    */
   public function setName($name) {
@@ -50,6 +57,13 @@ final class ArcanistFileDataRef extends Phobject {
 
 
   /**
+   * Set the data to upload as a single raw blob.
+   *
+   * You can specify file data by calling this method with a single blob of
+   * data, or by calling @{method:setPath} and providing a path to a file on
+   * disk.
+   *
+   * @param bytes Blob of file data.
    * @task config
    */
   public function setData($data) {
@@ -67,6 +81,16 @@ final class ArcanistFileDataRef extends Phobject {
 
 
   /**
+   * Set the data to upload by pointing to a file on disk.
+   *
+   * You can specify file data by calling this method with a path, or by
+   * providing a blob of raw data to @{method:setData}.
+   *
+   * The path itself only provides data. If you want to name the file, you
+   * should also call @{method:setName}.
+   *
+   * @param string Path on disk to a file containing data to upload.
+   * @return this
    * @task config
    */
   public function setPath($path) {
diff --git a/src/upload/ArcanistFileUploader.php b/src/upload/ArcanistFileUploader.php
index 60b26442..955cdbdc 100644
--- a/src/upload/ArcanistFileUploader.php
+++ b/src/upload/ArcanistFileUploader.php
@@ -33,6 +33,10 @@ final class ArcanistFileUploader extends Phobject {
 
 
   /**
+   * Provide a Conduit client to choose which server to upload files to.
+   *
+   * @param ConduitClient Configured client.
+   * @return this
    * @task config
    */
   public function setConduitClient(ConduitClient $conduit) {
@@ -45,6 +49,10 @@ final class ArcanistFileUploader extends Phobject {
 
 
   /**
+   * Add a file to the list of files to be uploaded.
+   *
+   * You can optionally provide an explicit key which will be used to identify
+   * the file. After adding files, upload them with @{method:uploadFiles}.
    *
    * @param ArcanistFileDataRef File data to upload.
    * @param null|string Optional key to use to identify this file.
@@ -74,10 +82,19 @@ final class ArcanistFileUploader extends Phobject {
 
 
   /**
+   * Upload files to the server.
+   *
+   * This transfers all files which have been queued with @{method:addFiles}
+   * over the Conduit link configured with @{method:setConduitClient}.
+   *
    * This method returns a map of all file data references. If references were
    * added with an explicit key when @{method:addFile} was called, the key is
    * retained in the result map.
    *
+   * On return, files are either populated with a PHID (indicating a successful
+   * upload) or a list of errors. See @{class:ArcanistFileDataRef} for
+   * details.
+   *
    * @return map<string, ArcanistFileDataRef> Files with results populated.
    * @task upload
    */
@@ -192,6 +209,9 @@ final class ArcanistFileUploader extends Phobject {
 
 
   /**
+   * Upload missing chunks of a large file by calling `file.uploadchunk` over
+   * Conduit.
+   *
    * @task internal
    */
   private function uploadChunks(ArcanistFileDataRef $file, $file_phid) {
@@ -253,6 +273,8 @@ final class ArcanistFileUploader extends Phobject {
 
 
   /**
+   * Upload an entire file by calling `file.upload` over Conduit.
+   *
    * @task internal
    */
   private function uploadData(ArcanistFileDataRef $file) {
@@ -270,10 +292,12 @@ final class ArcanistFileUploader extends Phobject {
 
 
   /**
+   * Write a status message.
+   *
    * @task internal
    */
   private function writeStatus($message) {
-    echo $message."\n";
+    fwrite(STDERR, $message."\n");
   }
 
 }