From 73db18ea4060ccb9d4524099f30954c20dad252a Mon Sep 17 00:00:00 2001 From: Mark Banner Date: Sat, 1 Apr 2023 16:40:02 +0000 Subject: [PATCH] Bug 1825715 - Add section about ignoring formatting to ESLint docs. r=Gijs This also does a general clean-up of the ESLint doc. Differential Revision: https://phabricator.services.mozilla.com/D174218 --- docs/code-quality/lint/linters/eslint.rst | 46 ++++++++++++++--------- 1 file changed, 28 insertions(+), 18 deletions(-) diff --git a/docs/code-quality/lint/linters/eslint.rst b/docs/code-quality/lint/linters/eslint.rst index 24adca2aefd8..da1ad925d1b5 100644 --- a/docs/code-quality/lint/linters/eslint.rst +++ b/docs/code-quality/lint/linters/eslint.rst @@ -23,7 +23,7 @@ See the `Usage guide`_ for more options. Understanding Rules and Errors ------------------------------ -* Only some files are linted, see the `configuration`_ for details. +* Only some files are linted, see the :searchfox:`configuration ` for details. * By design we do not lint/format reftests not crashtests as these are specially crafted tests. @@ -55,6 +55,8 @@ I am getting a linter error "Unknown Services member property" Make sure to add any new Services to ``tools/lint/eslint/eslint-plugin-mozilla/lib/services.json``. For example by copying from ``/xpcom/components/services.json`` after a build. +.. _adding-tests: + I'm adding tests, how do I set up the right configuration? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -89,20 +91,33 @@ I'm using an ES module * If it is a system module (e.g. component definition or other non-frontend code), use a ``.sys.mjs`` extension. -This code shouldn't be linted -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +This code should neither be linted nor formatted +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -* If it is a third-party piece of code, please add it to `ThirdPartyPaths.txt`_. -* If it is pre-generated file or intentionally invalid, please add it to `.eslintignore`_ +* If it is a third-party piece of code, please add it to :searchfox:`ThirdPartyPaths.txt `. +* If it is a generated file, please add it to :searchfox:`Generated.txt `. +* If intentionally invalid, please add it to :searchfox:`.eslintignore <.eslintignore>`. + +This code shouldn't be formatted +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The vast majority of code should be formatted, however we allow some limited +cases where it makes sense, for example: + +* A table in an array where laying it out in a table fashion makes it more readable. +* Other structures or function calls where layout is more readable in a particular format. + +To disable prettier for code like this, ``// prettier-ignore`` may be used on +the line previous to where you want it disabled. +See the `prettier ignore docs`_ for more information. I have valid code that is failing the ``no-undef`` rule or can't be parsed ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -* Please do not add this to `.eslintignore`_. Generally this can be fixed, if the following - tips don't help, please `seek help`_. -* If you are adding a new test directory, make sure its name matches one of the - `patterns in .eslintrc.js`_. If you really can't match those, then you may need - to add a separate `test specific .eslintrc.js file (example)`_. +* Please do not add this to :searchfox:`.eslintignore <.eslintignore>`. Generally + this can be fixed, if the following tips don't help, please `seek help`_. +* If you are adding a new test directory, see the :ref:`section above ` + * If you are writing a script loaded into special environment (e.g. frame script) you may need to tell ESLint to use the `environment definitions`_ for each case: * ``/* eslint-env mozilla/frame-script */`` @@ -129,8 +144,8 @@ make it easier for developers. Sources ------- -* `Configuration (YAML)`_ -* `Source`_ +* :searchfox:`Configuration (YAML) ` +* :searchfox:`Source ` Builders -------- @@ -184,18 +199,13 @@ For test harness issues, file bugs in Developer Infrastructure :: Lint and Forma .. _Prettier: https://prettier.io/ .. _Usage guide: ../usage.html .. _ESLint's documentation: http://eslint.org/docs/user-guide/configuring -.. _configuration: https://searchfox.org/mozilla-central/source/tools/lint/eslint.yml .. _eslint.org's rule list: http://eslint.org/docs/rules/ .. _eslint-plugin-mozilla: eslint-plugin-mozilla.html .. _eslint-plugin-spidermonkey-js: eslint-plugin-spidermonkey-js.html -.. _ThirdPartyPaths.txt: https://searchfox.org/mozilla-central/source/tools/rewriting/ThirdPartyPaths.txt .. _informed that it is a module: https://searchfox.org/mozilla-central/rev/9399e5832979755cd340383f4ca4069dd5fc7774/browser/base/content/.eslintrc.js -.. _.eslintignore: https://searchfox.org/mozilla-central/source/.eslintignore .. _seek help: ../index.html#getting-help .. _patterns in .eslintrc.js: https://searchfox.org/mozilla-central/rev/9399e5832979755cd340383f4ca4069dd5fc7774/.eslintrc.js#24-38 -.. _test specific .eslintrc.js file (example): https://searchfox.org/mozilla-central/source/browser/base/content/test/about/.eslintrc.js .. _environment definitions: ./eslint-plugin-mozilla/environment.html -.. _Configuration (YAML): https://searchfox.org/mozilla-central/source/tools/lint/eslint.yml -.. _Source: https://searchfox.org/mozilla-central/source/tools/lint/eslint/__init__.py .. _known ones: https://searchfox.org/mozilla-central/rev/287583a4a605eee8cd2d41381ffaea7a93d7b987/.eslintrc.js#24-40 .. _difficult for ESLint to handle: https://bugzilla.mozilla.org/show_bug.cgi?id=1379669 +.. _prettier ignore docs: https://prettier.io/docs/en/ignore.html