Some documentation.

Summary:

Test Plan:

Reviewers:

CC:

.divinerconfig

@@ -3,7 +3,17 @@
   "src_base" : "https://github.com/facebook/arcanist/blob/master",
   "groups" : {
     "intro" : "Introduction",
-    "config" : "Setup & Configuration"
+    "config" : "Setup & Configuration",    
+    "workflow" : "Workflows",
+    "lint" : "Lint Integration",
+    "linter" : "Linters",
+    "unit" : "Unit Test Integration",
+    "unitrun" : "Unit Test Runners",
+    "diff" : "Diff and Changeset APIs",
+    "differential" : "Differential Integration",
+    "workingcopy" : "Working Copy APIs",
+    "module" : "Phutil Module System",
+    "testcase" : "Test Cases"
   }
 }
 

scripts/arcanist.php

@@ -30,6 +30,8 @@ phutil_require_module('arcanist', 'configuration');
 phutil_require_module('arcanist', 'workingcopyidentity');
 phutil_require_module('arcanist', 'repository/api/base');
 
+ini_set('memory_limit', -1);
+
 $config_trace_mode = false;
 $force_conduit = null;
 $args = array_slice($argv, 1);

scripts/phutil_analyzer.php

@@ -53,7 +53,7 @@ phutil_require_module('phutil', 'parser/xhpast/api/tree');
 
 phutil_require_module('arcanist', 'lint/linter/phutilmodule');
 phutil_require_module('arcanist', 'lint/message');
-phutil_require_module('arcanist', 'staticanalysis/parsers/phutilmodule');
+phutil_require_module('arcanist', 'parser/phutilmodule');
 
 
 $data = array();
@@ -114,7 +114,7 @@ foreach (Futures($futures) as $file => $future) {
         }
         $requirements->addSourceDependency($name, $value);
       } else if ($call_name == 'phutil_require_module') {
-        analyze_require_module($call, $requirements);
+        analyze_phutil_require_module($call, $requirements);
       }
     }
   } else {
@@ -146,7 +146,7 @@ foreach (Futures($futures) as $file => $future) {
 
       $call_name = $name->getConcreteString();
       if ($call_name == 'phutil_require_module') {
-        analyze_require_module($call, $requirements);
+        analyze_phutil_require_module($call, $requirements);
       } else if ($call_name == 'call_user_func' ||
                  $call_name == 'call_user_func_array') {
         $params = $call->getChildByIndex(1)->getChildren();
@@ -307,7 +307,12 @@ if (!$has_init && $has_files) {
 
 echo json_encode($requirements->toDictionary());
 
-function analyze_require_module(
+/**
+ * Parses meaning from calls to phutil_require_module() in __init__.php files.
+ *
+ * @group module
+ */
+function analyze_phutil_require_module(
   XHPASTNode $call,
   PhutilModuleRequirements $requirements) {
 

src/__phutil_library_map__.php

@@ -68,7 +68,7 @@ phutil_register_library_map(array(
     'ArcanistXHPASTLinter' => 'lint/linter/xhpast',
     'ArcanistXHPASTLinterTestCase' => 'lint/linter/xhpast/__tests__',
     'PhutilLintEngine' => 'lint/engine/phutil',
-    'PhutilModuleRequirements' => 'staticanalysis/parsers/phutilmodule',
+    'PhutilModuleRequirements' => 'parser/phutilmodule',
     'PhutilUnitTestEngine' => 'unit/engine/phutil',
     'PhutilUnitTestEngineTestCase' => 'unit/engine/phutil/__tests__',
     'UnitTestableArcanistLintEngine' => 'lint/engine/test',

src/configuration/ArcanistConfiguration.php

@@ -16,6 +16,28 @@
  * limitations under the License.
  */
 
+/**
+ * Runtime workflow configuration. In Arcanist, commands you type like
+ * "arc diff" or "arc lint" are called "workflows". This class allows you to add
+ * new workflows (and extend existing workflows) by subclassing it and then
+ * pointing to your subclass in your project configuration.
+ *
+ * For instructions on how to extend this class and customize Arcanist in your
+ * project, see @{article:Building New Configuration Classes}.
+ *
+ * When specified as the **arcanist_configuration** class in your project's
+ * ##.arcconfig##, your subclass will be instantiated (instead of this class)
+ * and be able to handle all the method calls. In particular, you can:
+ *
+ *    - create, replace, or disable workflows by overriding buildWorkflow()
+ *      and buildAllWorkflows();
+ *    - add additional steps before or after workflows run by overriding
+ *      willRunWorkflow() or didRunWorkflow(); and
+ *    - add new flags to existing workflows by overriding
+ *      getCustomArgumentsForCommand().
+ *
+ * @group config
+ */
 class ArcanistConfiguration {
 
   public function buildWorkflow($command) {

src/difference/ArcanistDiffUtils.php

@@ -16,6 +16,11 @@
  * limitations under the License.
  */
 
+/**
+ * Dumping ground for diff- and diff-algorithm-related miscellany.
+ *
+ * @group diff
+ */
 final class ArcanistDiffUtils {
 
   public static function renderDifferences(

src/differential/commitmessage/ArcanistDifferentialCommitMessage.php

@@ -16,6 +16,11 @@
  * limitations under the License.
  */
 
+/**
+ * Represents a parsed commit message.
+ *
+ * @group differential
+ */
 class ArcanistDifferentialCommitMessage {
 
   private $rawCorpus;

src/differential/commitmessage/ArcanistDifferentialCommitMessageParserException.php

@@ -16,6 +16,11 @@
  * limitations under the License.
  */
 
+/**
+ * Thrown when a commit message isn't parseable.
+ *
+ * @group differential
+ */
 class ArcanistDifferentialCommitMessageParserException extends Exception {
 
 }

src/differential/revision/ArcanistDifferentialRevisionRef.php

@@ -16,6 +16,11 @@
  * limitations under the License.
  */
 
+/**
+ * Reference to a Differential revision.
+ *
+ * @group differential
+ */
 class ArcanistDifferentialRevisionRef {
 
   protected $id;

src/docs/arcconfig.diviner

@@ -1,8 +1,7 @@
 @title Setting Up .arcconfig
 @group config
 
-This document describes how to configure Arcanist projects with ##.arcconfig##
+Explains how to configure Arcanist projects with ##.arcconfig## files.
-files.
 
 = .arcconfig Basics =
 

src/docs/building_new_configuration_classes.diviner

@@ -0,0 +1,83 @@
+@title Building New Configuration Classes
+@group config
+
+Explains how to build new classes to control how Arcanist behaves.
+
+= Overview =
+
+Arcanist has some basic configuration options available in the ##.arcconfig##
+file (see @{article:Setting Up .arcconfig}), but it can't handle everything. If
+you want to customize Arcanist at a deeper level, you need to build new classes.
+For instance:
+
+  - if you want to configure linters, or add new linters, you need to create a
+    new class which extends @{class:ArcanistLintEngine}.
+  - if you want to integrate with a unit testing framework, you need to create a
+    new class which extends @{class:ArcanistBaseUnitTestEngine}.
+  - if you you want to change how workflows behave, or add new workflows, you
+    need to create a new class which extends @{class:ArcanistConfiguration}.
+
+Arcanist works through a sort of dependency-injection approach. For example,
+Arcanist does not run lint rules by default, but you can set **lint_engine**
+in your ##.arcconfig## to the name of a class which extends
+@{class:ArcanistLintEngine}. When running from inside your project, Arcanist
+will load this class and call methods on it in order to run lint. To make this
+work, you need to do three things:
+
+  - actually write the class;
+  - add the library where the class exists to your ##.arcconfig##;
+  - add the class name to your ##.arcconfig## as the **lint_engine**, 
+    **unit_engine**, or **arcanist_configuration**.
+    
+= Write the Class =
+
+(TODO)
+
+= Load the Class =
+
+To make the class loadable, you need to put the path to it in your
+##.arcconfig##, under **phutil_libraries**:
+
+  {
+    // ...
+    "phutil_libraries" : {
+      // ...
+      "my-library" : "/path/to/my/library",
+      // ...
+    }
+    // ...
+  }
+  
+You can either specify an absolute path, or a path relative to the project root.
+When you run ##arc --trace##, you should see a message to the effect that it has
+loaded your library.
+
+For debugging or testing, you can also run Arcanist with the
+##--load-phutil-library## flag:
+
+  arc --load-phutil-library=/path/to/library <command>
+  
+You can specify this flag more than once to load several libraries. Note that
+if you use this flag, Arcanist will ignore any libraries listed in
+##.arcconfig##.
+
+= Use the Class =
+
+This step is easy: just edit ##.arcconfig## to specify your class name as
+the appropriate configuration value.
+
+  {
+    // ...
+    "lint_engine" : "MyCustomArcanistLintEngine",
+    // ...
+  }
+
+Now, when you run Arcanist in your project, it will invoke your class when
+appropriate.
+
+For lint and unit tests, you can also use the ##--engine## flag override the
+default engine:
+
+  arc lint --engine MyCustomArcanistLintEngine
+
+This is mostly useful for debugging and testing.

src/docs/overview.diviner

@@ -1,10 +1,10 @@
 @title Arcanist Overview
 @group intro
 
-This document provides an overview of Arcanist, a code workflow tool. Arcanist
+Overview of Arcanist, a code workflow tool.
-(commonly, "arc") is the command-line frontend to Differential.
 
-A detailed command reference is available by running ##arc help##.
+Arcanist (commonly, "arc") is the command-line frontend to Differential. A
+detailed command reference is available by running ##arc help##.
 
 = Overview =
 

src/docs/svn_hooks.diviner

@@ -1,6 +1,8 @@
 @title Installing Arcanist SVN Hooks
 @group config
 
+Describes how to set up Arcanist as an SVN pre-commit hook.
+
 = Installing Arcanist SVN Hooks =
 
 You can install Arcanist as an SVN pre-commit hook, to reject commits which

src/exception/ArcanistChooseInvalidRevisionException.php

@@ -16,6 +16,11 @@
  * limitations under the License.
  */
 
+/**
+ * Thrown when the user chooses an invalid revision when prompted by a workflow.
+ *
+ * @group workflow
+ */
 class ArcanistChooseInvalidRevisionException extends Exception {
 
 }

src/exception/ArcanistChooseNoRevisionsException.php

@@ -16,6 +16,12 @@
  * limitations under the License.
  */
 
+/**
+ * Thrown when there are no valid revisions to choose from, in a workflow which
+ * prompts the user to choose a revision.
+ *
+ * @group workflow
+ */
 class ArcanistChooseNoRevisionsException extends Exception {
 
 }

src/exception/usage/ArcanistUsageException.php

@@ -16,6 +16,12 @@
  * limitations under the License.
  */
 
+/**
+ * Thrown when there is a problem with how a user is invoking a command, rather
+ * than a technical problem.
+ *
+ * @group workflow
+ */
 class ArcanistUsageException extends Exception {
 
 }

src/exception/usage/noeffect/ArcanistNoEffectException.php

@@ -16,5 +16,11 @@
  * limitations under the License.
  */
 
+/**
+ * Thrown when lint or unit tests have no effect, i.e. no paths are affected
+ * by any linter or no unit tests provide coverage.
+ *
+ * @group workflow
+ */
 class ArcanistNoEffectException extends ArcanistUsageException {
 }

src/exception/usage/noengine/ArcanistNoEngineException.php

@@ -16,5 +16,10 @@
  * limitations under the License.
  */
 
+/**
+ * Thrown when no engine is configured for linting or running unit tests.
+ *
+ * @group workflow
+ */
 class ArcanistNoEngineException extends ArcanistUsageException {
 }

src/exception/usage/userabort/ArcanistUserAbortException.php

@@ -16,6 +16,12 @@
  * limitations under the License.
  */
 
+/**
+ * Thrown when the user chooses not to continue when warned that they're about
+ * to do something dangerous.
+ *
+ * @group workflow
+ */
 class ArcanistUserAbortException extends ArcanistUsageException {
   public function __construct() {
     parent::__construct('User aborted the workflow.');

src/lint/engine/base/ArcanistLintEngine.php

@@ -16,6 +16,11 @@
  * limitations under the License.
  */
 
+/**
+ * Manages lint execution.
+ *
+ * @group lint
+ */
 abstract class ArcanistLintEngine {
 
   protected $workingCopy;

src/lint/engine/phutil/PhutilLintEngine.php

@@ -16,6 +16,11 @@
  * limitations under the License.
  */
 
+/**
+ * Lint engine which enforces libphutil rules.
+ *
+ * @group linter
+ */
 class PhutilLintEngine extends ArcanistLintEngine {
 
   public function buildLinters() {

src/lint/engine/test/UnitTestableArcanistLintEngine.php

@@ -16,6 +16,12 @@
  * limitations under the License.
  */
 
+/**
+ * Lint engine for use in constructing test cases. See
+ * @{class:ArcanistLinterTestCase}.
+ *
+ * @group testcase
+ */
 final class UnitTestableArcanistLintEngine extends ArcanistLintEngine {
 
   protected $linters = array();

src/lint/linter/apachelicense/ArcanistApacheLicenseLinter.php

@@ -16,6 +16,11 @@
  * limitations under the License.
  */
 
+/**
+ * Adds the Apache license to source files.
+ *
+ * @group linter
+ */
 class ArcanistApacheLicenseLinter extends ArcanistLicenseLinter {
   public function getLinterName() {
     return 'APACHELICENSE';

src/lint/linter/apachelicense/__tests__/ArcanistApacheLicenseLinterTestCase.php

@@ -16,6 +16,11 @@
  * limitations under the License.
  */
 
+/**
+ * Test cases for @{class:ArcanistApacheLicenseLinter}.
+ *
+ * @group testcase
+ */
 class ArcanistApacheLicenseLinterTestCase extends ArcanistLinterTestCase {
 
   public function testApacheLicenseLint() {

src/lint/linter/base/ArcanistLinter.php

@@ -16,6 +16,11 @@
  * limitations under the License.
  */
 
+/**
+ * Implements lint rules, like syntax checks for a specific language.
+ *
+ * @group linter
+ */
 abstract class ArcanistLinter {
 
   protected $paths  = array();

src/lint/linter/base/test/ArcanistLinterTestCase.php

@@ -16,6 +16,11 @@
  * limitations under the License.
  */
 
+/**
+ * Facilitiates implementation of test cases for @{class:ArcanistLinter}s.
+ *
+ * @group testcase
+ */
 abstract class ArcanistLinterTestCase extends ArcanistPhutilTestCase {
 
   public function executeTestsInDirectory($root, $linter, $working_copy) {

src/lint/linter/filename/ArcanistFilenameLinter.php

@@ -16,6 +16,11 @@
  * limitations under the License.
  */
 
+/**
+ * Stifles creativity in choosing imaginative file names.
+ *
+ * @group linter
+ */
 class ArcanistFilenameLinter extends ArcanistLinter {
 
   const LINT_BAD_FILENAME = 1;

src/lint/linter/generated/ArcanistGeneratedLinter.php

@@ -1,8 +1,9 @@
 <?php
 
 /**
- * This linter just stops the lint process when a file is marked as generated
+ * Stops other linters from running on generated code.
- * code.
+ *
+ * @group linter
  */
 class ArcanistGeneratedLinter extends ArcanistLinter {
 

src/lint/linter/license/ArcanistLicenseLinter.php

@@ -16,6 +16,11 @@
  * limitations under the License.
  */
 
+/**
+ * Adds a license or copyright header to source files.
+ *
+ * @group linter
+ */
 abstract class ArcanistLicenseLinter extends ArcanistLinter {
   const LINT_NO_LICENSE_HEADER = 1;
 

src/lint/linter/pep8/ArcanistPEP8Linter.php

@@ -16,6 +16,11 @@
  * limitations under the License.
  */
 
+/**
+ * Uses "pep8.py" to enforce PEP8 rules for Python.
+ *
+ * @group linter
+ */
 class ArcanistPEP8Linter extends ArcanistLinter {
 
   public function willLintPaths(array $paths) {

src/lint/linter/phutilmodule/ArcanistPhutilModuleLinter.php

@@ -16,6 +16,11 @@
  * limitations under the License.
  */
 
+/**
+ * Applies rules for modules in Phutil libraries.
+ *
+ * @group linter
+ */
 class ArcanistPhutilModuleLinter extends ArcanistLinter {
 
   const LINT_UNDECLARED_CLASS       = 1;

src/lint/linter/text/ArcanistTextLinter.php

@@ -16,6 +16,11 @@
  * limitations under the License.
  */
 
+/**
+ * Enforces basic text file rules.
+ *
+ * @group linter
+ */
 class ArcanistTextLinter extends ArcanistLinter {
 
   const LINT_DOS_NEWLINE            = 1;

src/lint/linter/text/__tests__/ArcanistTextLinterTestCase.php

@@ -16,6 +16,11 @@
  * limitations under the License.
  */
 
+/**
+ * Test cases for @{class:ArcanistTextLinter}.
+ *
+ * @group testcase
+ */
 class ArcanistTextLinterTestCase extends ArcanistLinterTestCase {
 
   public function testTextLint() {

src/lint/linter/xhpast/ArcanistXHPASTLinter.php

@@ -16,6 +16,11 @@
  * limitations under the License.
  */
 
+/**
+ * Uses XHPAST to apply lint rules to PHP or PHP+XHP.
+ *
+ * @group linter
+ */
 class ArcanistXHPASTLinter extends ArcanistLinter {
 
   private $trees = array();

src/lint/linter/xhpast/__tests__/ArcanistXHPASTLinterTestCase.php

@@ -16,6 +16,11 @@
  * limitations under the License.
  */
 
+/**
+ * Tests for @{class:ArcanistXHPASTLinter}.
+ *
+ * @group testcase
+ */
 class ArcanistXHPASTLinterTestCase extends ArcanistLinterTestCase {
 
   public function testXHPASTLint() {

src/lint/message/ArcanistLintMessage.php

@@ -16,6 +16,11 @@
  * limitations under the License.
  */
 
+/**
+ * Message emitted by a linter, like an error or warning.
+ *
+ * @group lint
+ */
 class ArcanistLintMessage {
 
   protected $path;

src/lint/patcher/ArcanistLintPatcher.php

@@ -16,6 +16,11 @@
  * limitations under the License.
  */
 
+/**
+ * Applies lint patches to the working copy.
+ *
+ * @group lint
+ */
 final class ArcanistLintPatcher {
 
   private $dirtyUntil     = 0;

src/lint/renderer/ArcanistLintRenderer.php

@@ -16,6 +16,11 @@
  * limitations under the License.
  */
 
+/**
+ * Shows lint messages to the user.
+ *
+ * @group lint
+ */
 class ArcanistLintRenderer {
 
   private $summaryMode;

src/lint/result/ArcanistLintResult.php

@@ -16,6 +16,11 @@
  * limitations under the License.
  */
 
+/**
+ * A group of @{class:ArcanistLintMessage}s that apply to a file.
+ *
+ * @group lint
+ */
 final class ArcanistLintResult {
 
   protected $path;

src/lint/severity/ArcanistLintSeverity.php

@@ -16,6 +16,11 @@
  * limitations under the License.
  */
 
+/**
+ * Describes the severity of an @{class:ArcanistLintMessage}.
+ *
+ * @group lint
+ */
 class ArcanistLintSeverity {
 
   const SEVERITY_ADVICE       = 'advice';

src/parser/bundle/ArcanistBundle.php

@@ -16,6 +16,11 @@
  * limitations under the License.
  */
 
+/**
+ * Converts changesets between different formats.
+ *
+ * @group diff
+ */
 class ArcanistBundle {
 
   private $changes;

src/parser/diff/ArcanistDiffParser.php

@@ -16,6 +16,11 @@
  * limitations under the License.
  */
 
+/**
+ * Parses diffs from a working copy.
+ *
+ * @group diff
+ */
 class ArcanistDiffParser {
 
   protected $api;

src/parser/diff/__tests__/ArcanistDiffParserTestCase.php

@@ -16,6 +16,11 @@
  * limitations under the License.
  */
 
+/**
+ * Test cases for @{class:ArcanistDiffParser}.
+ *
+ * @group testcase
+ */
 class ArcanistDiffParserTestCase extends ArcanistPhutilTestCase {
 
   public function testParser() {

src/parser/diff/change/ArcanistDiffChange.php

@@ -16,6 +16,11 @@
  * limitations under the License.
  */
 
+/**
+ * Represents a change to an individual path.
+ *
+ * @group diff
+ */
 class ArcanistDiffChange {
 
   protected $metadata = array();

src/parser/diff/changetype/ArcanistDiffChangeType.php

@@ -16,6 +16,11 @@
  * limitations under the License.
  */
 
+/**
+ * Defines constants for file types and operations in changesets.
+ *
+ * @group diff
+ */
 class ArcanistDiffChangeType {
   const TYPE_ADD        = 1;
   const TYPE_CHANGE     = 2;

src/parser/diff/hunk/ArcanistDiffHunk.php

@@ -17,8 +17,9 @@
  */
 
 /**
- * A hunk is a contiguous set of added and removed lines in a diff. This is
+ * Represents a contiguous set of added and removed lines in a diff.
- * the parsed representation thereof.
+ *
+ * @group diff
  */
 class ArcanistDiffHunk {
 

src/parser/phutilmodule/PhutilModuleRequirements.php

@@ -16,6 +16,11 @@
  * limitations under the License.
  */
 
+/**
+ * Lists dependencies and requirements for a module.
+ *
+ * @group module
+ */
 class PhutilModuleRequirements {
 
   protected $builtins = array(

src/repository/api/base/ArcanistRepositoryAPI.php

@@ -16,6 +16,11 @@
  * limitations under the License.
  */
 
+/**
+ * Interfaces with the VCS in the working copy.
+ *
+ * @group workingcopy
+ */
 abstract class ArcanistRepositoryAPI {
 
   const FLAG_MODIFIED     = 1;

src/repository/api/git/ArcanistGitAPI.php

@@ -16,6 +16,11 @@
  * limitations under the License.
  */
 
+/**
+ * Interfaces with Git working copies.
+ *
+ * @group workingcopy
+ */
 class ArcanistGitAPI extends ArcanistRepositoryAPI {
 
   private $status;

src/repository/api/subversion/ArcanistSubversionAPI.php

@@ -16,6 +16,11 @@
  * limitations under the License.
  */
 
+/**
+ * Interfaces with Subversion working copies.
+ *
+ * @group workingcopy
+ */
 class ArcanistSubversionAPI extends ArcanistRepositoryAPI {
 
   protected $svnStatus;

src/unit/engine/base/ArcanistBaseUnitTestEngine.php

@@ -16,6 +16,11 @@
  * limitations under the License.
  */
 
+/**
+ * Manages unit test execution.
+ *
+ * @group unit
+ */
 abstract class ArcanistBaseUnitTestEngine {
 
   private $workingCopy;

src/unit/engine/phutil/PhutilUnitTestEngine.php

@@ -16,6 +16,11 @@
  * limitations under the License.
  */
 
+/**
+ * Very basic unit test engine which runs libphutil tests.
+ *
+ * @group unitrun
+ */
 class PhutilUnitTestEngine extends ArcanistBaseUnitTestEngine {
 
   public function run() {

src/unit/engine/phutil/__tests__/PhutilUnitTestEngineTestCase.php

@@ -16,6 +16,11 @@
  * limitations under the License.
  */
 
+/**
+ * Very meta test for @{class:PhutilUnitTestEngine}.
+ *
+ * @group testcase
+ */
 class PhutilUnitTestEngineTestCase extends ArcanistPhutilTestCase {
 
   public function testPass() {

src/unit/engine/phutil/testcase/ArcanistPhutilTestCase.php

@@ -16,6 +16,11 @@
  * limitations under the License.
  */
 
+/**
+ * Base test case for the very simple libphutil test framework.
+ *
+ * @group unitrun
+ */
 abstract class ArcanistPhutilTestCase {
 
   private $runningTest;

src/unit/engine/phutil/testcase/exception/ArcanistPhutilTestTerminatedException.php

@@ -16,4 +16,9 @@
  * limitations under the License.
  */
 
+/**
+ * Thrown to prematurely end test execution.
+ *
+ * @group unitrun
+ */
 class ArcanistPhutilTestTerminatedException extends Exception {}

src/unit/result/ArcanistUnitTestResult.php

@@ -16,6 +16,11 @@
  * limitations under the License.
  */
 
+/**
+ * Represents the outcome of running a unit test.
+ *
+ * @group unit
+ */
 class ArcanistUnitTestResult {
 
   const RESULT_PASS         = 'pass';

src/workflow/amend/ArcanistAmendWorkflow.php

@@ -16,6 +16,11 @@
  * limitations under the License.
  */
 
+/**
+ * Updates git commit messages after a revision is "Accepted".
+ *
+ * @group workflow
+ */
 class ArcanistAmendWorkflow extends ArcanistBaseWorkflow {
 
   public function getCommandHelp() {

src/workflow/base/ArcanistBaseWorkflow.php

@@ -16,6 +16,11 @@
  * limitations under the License.
  */
 
+/**
+ * Implements a runnable command, like "arc diff" or "arc help".
+ *
+ * @group workflow
+ */
 class ArcanistBaseWorkflow {
 
   private $conduit;

src/workflow/commit/ArcanistCommitWorkflow.php

@@ -16,6 +16,11 @@
  * limitations under the License.
  */
 
+/**
+ * Executes "svn commit" once a revision has been "Accepted".
+ *
+ * @group workflow
+ */
 class ArcanistCommitWorkflow extends ArcanistBaseWorkflow {
 
   public function getCommandHelp() {

src/workflow/cover/ArcanistCoverWorkflow.php

@@ -16,6 +16,11 @@
  * limitations under the License.
  */
 
+/**
+ * Covers your professional reputation by blaming changes to locate reviewers.
+ *
+ * @group workflow
+ */
 class ArcanistCoverWorkflow extends ArcanistBaseWorkflow {
 
   public function getCommandHelp() {

src/workflow/diff/ArcanistDiffWorkflow.php

@@ -16,6 +16,11 @@
  * limitations under the License.
  */
 
+/**
+ * Sends changes from your working copy to Differential for code review.
+ *
+ * @group workflow
+ */
 class ArcanistDiffWorkflow extends ArcanistBaseWorkflow {
 
   private $hasWarnedExternals = false;

src/workflow/export/ArcanistExportWorkflow.php

@@ -16,6 +16,11 @@
  * limitations under the License.
  */
 
+/**
+ * Exports changes from Differential or the working copy to a file.
+ *
+ * @group workflow
+ */
 final class ArcanistExportWorkflow extends ArcanistBaseWorkflow {
 
   const SOURCE_LOCAL      = 'local';

src/workflow/git-hook-pre-receive/ArcanistGitHookPreReceiveWorkflow.php

@@ -16,6 +16,11 @@
  * limitations under the License.
  */
 
+/**
+ * Installable as a git pre-receive hook.
+ *
+ * @group workflow
+ */
 class ArcanistGitHookPreReceiveWorkflow extends ArcanistBaseWorkflow {
 
   public function getCommandHelp() {

src/workflow/help/ArcanistHelpWorkflow.php

@@ -16,6 +16,11 @@
  * limitations under the License.
  */
 
+/**
+ * Seduces the reader with majestic prose.
+ *
+ * @group workflow
+ */
 class ArcanistHelpWorkflow extends ArcanistBaseWorkflow {
 
   public function getCommandHelp() {

src/workflow/lint/ArcanistLintWorkflow.php

@@ -16,6 +16,11 @@
  * limitations under the License.
  */
 
+/**
+ * Runs lint rules on changes.
+ *
+ * @group workflow
+ */
 class ArcanistLintWorkflow extends ArcanistBaseWorkflow {
 
   const RESULT_OKAY       = 0;

src/workflow/list/ArcanistListWorkflow.php

@@ -16,6 +16,11 @@
  * limitations under the License.
  */
 
+/**
+ * Lists open revisions in Differential.
+ *
+ * @group workflow
+ */
 class ArcanistListWorkflow extends ArcanistBaseWorkflow {
 
   public function getCommandHelp() {

src/workflow/mark-committed/ArcanistMarkCommittedWorkflow.php

@@ -16,6 +16,11 @@
  * limitations under the License.
  */
 
+/**
+ * Explicitly marks Differential revisions as "Committed".
+ *
+ * @group workflow
+ */
 class ArcanistMarkCommittedWorkflow extends ArcanistBaseWorkflow {
 
   public function getCommandHelp() {

src/workflow/patch/ArcanistPatchWorkflow.php

@@ -16,6 +16,11 @@
  * limitations under the License.
  */
 
+/**
+ * Applies changes from Differential or a file to the working copy.
+ *
+ * @group workflow
+ */
 final class ArcanistPatchWorkflow extends ArcanistBaseWorkflow {
 
   const SOURCE_BUNDLE     = 'bundle';

src/workflow/shell-complete/ArcanistShellCompleteWorkflow.php

@@ -16,6 +16,11 @@
  * limitations under the License.
  */
 
+/**
+ * Powers shell-completion scripts.
+ *
+ * @group workflow
+ */
 class ArcanistShellCompleteWorkflow extends ArcanistBaseWorkflow {
 
   public function getCommandHelp() {

src/workflow/svn-hook-pre-commit/ArcanistSvnHookPreCommitWorkflow.php

@@ -16,6 +16,11 @@
  * limitations under the License.
  */
 
+/**
+ * Installable as an SVN "pre-commit" hook.
+ *
+ * @group workflow
+ */
 class ArcanistSvnHookPreCommitWorkflow extends ArcanistBaseWorkflow {
 
   public function getCommandHelp() {

src/workflow/unit/ArcanistUnitWorkflow.php

@@ -16,6 +16,11 @@
  * limitations under the License.
  */
 
+/**
+ * Runs unit tests which cover your changes.
+ *
+ * @group workflow
+ */
 class ArcanistUnitWorkflow extends ArcanistBaseWorkflow {
 
   const RESULT_OKAY     = 0;

src/workflow/unit/__init__.php

@@ -7,6 +7,7 @@
 
 
 phutil_require_module('arcanist', 'exception/usage/noengine');
+phutil_require_module('arcanist', 'repository/api/base');
 phutil_require_module('arcanist', 'unit/result');
 phutil_require_module('arcanist', 'workflow/base');
 

src/workingcopyidentity/ArcanistWorkingCopyIdentity.php

@@ -16,6 +16,11 @@
  * limitations under the License.
  */
 
+/**
+ * Interfaces with basic information about the working copy.
+ *
+ * @group workingcopy
+ */
 class ArcanistWorkingCopyIdentity {
 
   protected $projectConfig;