Better document techniques for reusing linters

Summary: As per discussion with @johnduhart, improve documentation around
reusing and customizing linters.

Test Plan: Generated and read documentation.

Reviewers: btrahan, jungejason, johnduhart

Reviewed By: btrahan

CC: aran, epriestley

Maniphest Tasks: T795

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

src/docs/userguide/arcanist_extending_lint.diviner

@@ -0,0 +1,105 @@
+@title Arcanist User Guide: Customizing Existing Linters
+@group userguide
+
+Explains how to customize existing linters.
+
+= Overview =
+
+Arcanist ships with a number of linters which you may want to reuse in whole
+or in part in other projects. This document explains how to customize existing
+linters for use in new engines.
+
+First, you should set up a custom engine by following the steps in
+@{article:Arcanist User Guide: Customizing Lint, Unit Tests and Workflows}.
+Then, follow this guide to customize linters.
+
+= General Guidelines =
+
+You should customize linters by configuring or composing them, not by extending
+them -- their implementations are not necessarily stable. If a linter's
+configuration options aren't flexible enough to meet your needs, a patch
+which improves its configurability is better than one that makes it
+nonfinal.
+
+= Changing Rule Severities =
+
+By default, most linters raise lint messages as errors. You may want to reduce
+the severity of some messages (e.g., reduce errors to warnings). Do this by
+calling ##setCustomSeverityMap()##:
+
+  $linter = new ArcanistTextLinter();
+
+  // Change "missing newline at end of file" message from error to warning.
+  $linter->setCustomSeverityMap(
+    array(
+      ArcanistTextLinter::LINT_EOF_NEWLINE
+        => ArcanistLintSeverity::SEVERITY_WARNING,
+    ));
+
+See @{class@arcanist:ArcanistLintSeverity} for a list of available severity
+constants.
+
+= Disabling Rules =
+
+To disable rules entirely, set their severities to ##SEVERITY_DISABLED##:
+
+  $linter = new ArcanistTextLinter();
+
+  // Disable "Tab Literal" message.
+  $linter->setCustomSeverityMap(
+    array(
+      ArcanistTextLinter::LINT_TAB_LITERAL
+        => ArcanistLintSeverity::SEVERITY_DISABLED,
+    ));
+
+= Running Multiple Rulesets =
+
+If you want to run the same linter on different types of files but vary the
+configuration based on the file type, just instantiate it twice and configure
+each instance appropriately. For instance, this will enforce different column
+widths on different languages:
+
+  $linters = array();
+
+  $text_80col_linter = new ArcanistTextLinter();
+  $linters[] = $text_80col_linter;
+
+  $text_120col_linter = new ArcanistTextLinter();
+  $text_120col_linter->setMaxLineLength(120);
+  $linters[] = $text_120col_linter;
+
+  foreach ($paths as $path) {
+
+    // Warn on JS/CSS lines longer than 80 columns.
+    if (preg_match('/\.(js|css)$/', $path)) {
+      $text_80col_linter->addPath($path);
+    }
+
+    // Warn on Java lines longer than 120 columns.
+    if (preg_match('/\.java$/', $path)) {
+      $text_120col_linter->addPath($path);
+    }
+
+  }
+
+  // ...
+
+  return $linters;
+
+= Customizing Specific Linters =
+
+Some linters are specifically customizable or configurable. Some common
+options are documented here, consult class documentation for complete
+information.
+
+== ArcanistTextLinter ==
+
+  - Use ##setMaxLineLength()## to change the 80-column warning to something
+    else.
+
+== ArcanistXHPASTLinter ==
+
+  - Use ##lint.xhpast.naminghook## in ##.arcconfig## to override naming
+    convention rules. See @{class@arcanist:ArcanistXHPASTLintNamingHook}
+    for details, and @{class:PhabricatorSymbolNameLinter} for an example.
+  - Use ##getXHPASTTreeForPath()## to reuse the AAST in other linters.

src/docs/userguide/arcanist_lint_unit.diviner

@@ -80,3 +80,10 @@ default engine:
   arc lint --engine MyCustomArcanistLintEngine
 
 This is mostly useful for debugging and testing.
+
+= Next Steps =
+
+  - Browse the source for an example lint engine at
+    @{class@arcanist:ExampleLintEngine}; or
+  - learn how to reuse existing linters by reading
+    @{article:Arcanist User Guide: Customizing Existing Linters}.