From 793af17c22977667d0b8e5ee8925fe9b1d3c8f48 Mon Sep 17 00:00:00 2001
From: "J. King" <jking@jkingweb.ca>
Date: Sun, 17 Dec 2017 11:37:07 -0500
Subject: [PATCH] Pad out help for Robo tasks

---
 RoboFile.php | 52 ++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 46 insertions(+), 6 deletions(-)

diff --git a/RoboFile.php b/RoboFile.php
index ae515db7..4653e4c8 100644
--- a/RoboFile.php
+++ b/RoboFile.php
@@ -11,7 +11,16 @@ class RoboFile extends \Robo\Tasks {
     const BASE = __DIR__.\DIRECTORY_SEPARATOR;
     const BASE_TEST = self::BASE."tests".\DIRECTORY_SEPARATOR;
 
-    /** Runs the full test suite */
+    /** 
+     * Runs the full test suite 
+     * 
+     * Arguments passed to the task are passed on to PHPUnit. Thus one may, for 
+     * example, run the following command and get the expected results:
+     * 
+     * ./robo test --testsuite TTRSS --exclude-group slow --testdox 
+     * 
+     * Please see the PHPUnit documentation for available options. 
+    */
     public function test(array $args): Result {
         // start the built-in PHP server, which is required for some of the tests
         $this->taskServer(8000)->host("localhost")->dir(self::BASE_TEST."docroot")->rawArg("-n")->arg(self::BASE_TEST."server.php")->background()->run();
@@ -21,11 +30,34 @@ class RoboFile extends \Robo\Tasks {
         return $this->taskExec("php")->arg($execpath)->option("-c", $confpath)->args($args)->run();
     }
 
-    /** Runs a quick subset of the test suite */
+    /** 
+     * Runs the full test suite 
+     * 
+     * This is an alias of the "test" task. 
+    */
+    public function testFull(array $args): Result {
+        return $this->test($args);
+    }
+
+    /** 
+     * Runs a quick subset of the test suite 
+     * 
+     * See help for the "test" task for more details. 
+    */
     public function testQuick(array $args): Result {
         return $this->test(array_merge(["--exclude-group","slow"], $args));
     }
 
+    /** Produces a code coverage report 
+     * 
+     * By default this task produces an HTML-format coverage report in
+     * arsse/tests/coverage/. Additional reports may be produced by passing
+     * arguments to this task as one would to PHPUnit.
+     * 
+     * Robo first tries to use phpdbg and will fall back to Xdebug if available.
+     * Because Xdebug slows down non-coverage tasks, however, phpdbg is highly 
+     * recommanded is debugging facilities are not otherwise needed.
+    */
     public function coverage(array $args): Result {
         // start the built-in PHP server, which is required for some of the tests
         $this->taskServer(8000)->host("localhost")->dir(self::BASE_TEST."docroot")->rawArg("-n")->arg(self::BASE_TEST."server.php")->background()->run();
@@ -34,8 +66,6 @@ class RoboFile extends \Robo\Tasks {
         $execpath = realpath(self::BASE."vendor-bin/phpunit/vendor/phpunit/phpunit/phpunit");
         $confpath = realpath(self::BASE_TEST."phpunit.xml");
         return $this->taskExec($exec)->arg($execpath)->option("-c", $confpath)->option("--coverage-html", self::BASE_TEST."coverage")->args($args)->run();
-        // run the test suite with code coverage reporting enabled
-        return $this->test(array_merge(["--coverage-html",self::BASE_TEST."coverage"], $args));
     }
 
     protected function findCoverageEngine(): string {
@@ -49,9 +79,19 @@ class RoboFile extends \Robo\Tasks {
         }
     }
 
-    public function package(array $args): Result {
+    /** Packages a given commit of the software into a release tarball 
+     * 
+     * The version to package may be any Git tree-ish identifier: a tag, a branch,
+     * or any commit hash. If none is provided on the command line, Robo will prompt
+     * for a commit to package; the default is "head".
+     * 
+     * Note that while it is possible to re-package old versions, the resultant tarball
+     * may not be equivalent due to subsequent changes in the exclude list, or because 
+     * of new tooling.
+    */
+    public function package(string $version = null): Result {
         // establish which commit to package
-        $version = $args ? $args[0] : $this->askDefault("Commit to package:", "head");
+        $version = $version ?? $this->askDefault("Commit to package:", "head");
         $archive = self::BASE."arsse-$version.tar.gz";
         // start a collection
         $t = $this->collectionBuilder();