From 7d46e0263139445d2fb317a96de2ebd82848d78c Mon Sep 17 00:00:00 2001 From: epriestley Date: Sat, 28 Jan 2012 11:17:10 -0800 Subject: [PATCH] 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 --- .../userguide/arcanist_extending_lint.diviner | 105 ++++++++++++++++++ src/docs/userguide/arcanist_lint_unit.diviner | 7 ++ 2 files changed, 112 insertions(+) create mode 100644 src/docs/userguide/arcanist_extending_lint.diviner diff --git a/src/docs/userguide/arcanist_extending_lint.diviner b/src/docs/userguide/arcanist_extending_lint.diviner new file mode 100644 index 0000000000..7120cb5cec --- /dev/null +++ b/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. diff --git a/src/docs/userguide/arcanist_lint_unit.diviner b/src/docs/userguide/arcanist_lint_unit.diviner index 1129e40b07..6ddc3459b6 100644 --- a/src/docs/userguide/arcanist_lint_unit.diviner +++ b/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}.