From 9a6f4a7e68906f9c0cd29a2cbea49e2fe823ad6b Mon Sep 17 00:00:00 2001 From: Sam Rawlins Date: Sun, 9 Feb 2025 20:25:48 -0800 Subject: [PATCH 1/3] Add text regarding including shared analysis options --- src/content/tools/analysis.md | 73 +++++++++++++++++++++++++++++++++++ 1 file changed, 73 insertions(+) diff --git a/src/content/tools/analysis.md b/src/content/tools/analysis.md index 292077fca2..609dd97c70 100644 --- a/src/content/tools/analysis.md +++ b/src/content/tools/analysis.md @@ -310,6 +310,11 @@ Other options are to explicitly enable individual linter rules or [disable individual rules][]. ::: +:::note +For more information about including options files, see [including shared +options](#including-shared-options). +::: + [lints package]: {{site.pub-pkg}}/lints ### Enabling individual rules {:#individual-rules} @@ -368,6 +373,74 @@ Due to YAML restrictions, You can use the other syntax for rules in an included file. ::: +## Including shared options + +An analysis options file can include other options which are specified another +options file, or even a list of other options files. Specify such files with +the top-level `include:` field: + +```yaml title="analysis_options.yaml" +include: package:flutter_lints/recommended.yaml +``` + +An included options file can be specified with a `package:` path, or a relative +path. Multiple analysis options can be specified in a list: + +```yaml title="analysis_options.yaml" +include: + - package:flutter_lints/recommended.yaml + - ../team_options.yaml +``` + +Options found in an included file can be overridden in the including file. +Options found in an included file can also be overridden by subsequent included +files. For example, given the following options files: + +```yaml title="one.yaml" +analyzer: + errors: + dead_code: ignore + todo: ignore + unnecessary_import: ignore +``` + +```yaml title="two.yaml" +analyzer: + errors: + invalid_use_of_protected_member: ignore + unused_import: ignore +``` + +```yaml title="three.yaml" +include: two.yaml +analyzer: + errors: + unused_import: info + unnecessary_import: info +``` + +and a final options file that includes these: + +```yaml title="analysis_options.yaml" +include: + - one.yaml + - three.yaml +analyzer: + errors: + todo: warning + unused_import: warning +``` + +then the combined analysis options are as follows: + +* `dead_code` is ignored, as specified by `one.yaml`. +* `inavlid_use_of_protected_member` is ignored, as specified by `two.yaml`, + which is included in `three.yaml`. +* The severity of `todo` is 'warning,' as specified in the final file, + overriding the option set in `one.yaml`. +* The severity of `unused_import` is also `warning,' as specified in the final + file, overriding the option set in `two.yaml`. + ## Enabling analyzer plugins (experimental) {:#plugins} The analyzer has experimental support for plugins. From 715539a7b852f89407f5a6511fc945574a7fb283 Mon Sep 17 00:00:00 2001 From: Sam Rawlins Date: Mon, 10 Feb 2025 13:47:44 -0800 Subject: [PATCH 2/3] feedback --- src/content/tools/analysis.md | 49 ++++++++++------------------------- 1 file changed, 14 insertions(+), 35 deletions(-) diff --git a/src/content/tools/analysis.md b/src/content/tools/analysis.md index 609dd97c70..ec1c03cd35 100644 --- a/src/content/tools/analysis.md +++ b/src/content/tools/analysis.md @@ -375,16 +375,16 @@ You can use the other syntax for rules in an included file. ## Including shared options -An analysis options file can include other options which are specified another -options file, or even a list of other options files. Specify such files with -the top-level `include:` field: +An analysis options file can include other options which are specified in +another options file, or even a list of other options files. Specify such files +with the top-level `include:` field: ```yaml title="analysis_options.yaml" include: package:flutter_lints/recommended.yaml ``` An included options file can be specified with a `package:` path, or a relative -path. Multiple analysis options can be specified in a list: +path. Multiple analysis options files can be specified in a list: ```yaml title="analysis_options.yaml" include: @@ -394,29 +394,16 @@ include: Options found in an included file can be overridden in the including file. Options found in an included file can also be overridden by subsequent included -files. For example, given the following options files: +files. In other words, the options specified by an analysis options file are +computed by first applying the options specified in each of the included files +(by recursively applying this algorithm), in the order they appear in the list, +and then overriding them with any locally defined options. -```yaml title="one.yaml" -analyzer: - errors: - dead_code: ignore - todo: ignore - unnecessary_import: ignore -``` - -```yaml title="two.yaml" -analyzer: - errors: - invalid_use_of_protected_member: ignore - unused_import: ignore -``` +For example, given the following options files: ```yaml title="three.yaml" include: two.yaml -analyzer: - errors: - unused_import: info - unnecessary_import: info +# ... ``` and a final options file that includes these: @@ -425,21 +412,13 @@ and a final options file that includes these: include: - one.yaml - three.yaml -analyzer: - errors: - todo: warning - unused_import: warning +# ... ``` -then the combined analysis options are as follows: +then the combined analysis options are computed by applying the options found +in `one.yaml`, then `two.yaml`, then `three.yaml`, and finally +`analysis_options.yaml`. -* `dead_code` is ignored, as specified by `one.yaml`. -* `inavlid_use_of_protected_member` is ignored, as specified by `two.yaml`, - which is included in `three.yaml`. -* The severity of `todo` is 'warning,' as specified in the final file, - overriding the option set in `one.yaml`. -* The severity of `unused_import` is also `warning,' as specified in the final - file, overriding the option set in `two.yaml`. ## Enabling analyzer plugins (experimental) {:#plugins} From e54bd204e064f3c3ee43a69050e5d530edd8773a Mon Sep 17 00:00:00 2001 From: Marya <111139605+MaryaBelanger@users.noreply.github.com> Date: Tue, 11 Feb 2025 15:14:59 -0800 Subject: [PATCH 3/3] Apply suggestions from code review --- src/content/tools/analysis.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/src/content/tools/analysis.md b/src/content/tools/analysis.md index ec1c03cd35..2e10820ac7 100644 --- a/src/content/tools/analysis.md +++ b/src/content/tools/analysis.md @@ -311,8 +311,8 @@ or [disable individual rules][]. ::: :::note -For more information about including options files, see [including shared -options](#including-shared-options). +For more information about including options files, +check out the [Including shared options](#including-shared-options) section. ::: [lints package]: {{site.pub-pkg}}/lints @@ -375,9 +375,9 @@ You can use the other syntax for rules in an included file. ## Including shared options -An analysis options file can include other options which are specified in -another options file, or even a list of other options files. Specify such files -with the top-level `include:` field: +An analysis options file can include options which are specified in +another options file, or even a list of other options files. +You can specify such files using the top-level `include:` field: ```yaml title="analysis_options.yaml" include: package:flutter_lints/recommended.yaml @@ -392,9 +392,9 @@ include: - ../team_options.yaml ``` -Options found in an included file can be overridden in the including file. -Options found in an included file can also be overridden by subsequent included -files. In other words, the options specified by an analysis options file are +Options in an included file can be overridden in the including file, +as well as by subsequent included files. +In other words, the options specified by an analysis options file are computed by first applying the options specified in each of the included files (by recursively applying this algorithm), in the order they appear in the list, and then overriding them with any locally defined options. @@ -406,7 +406,7 @@ include: two.yaml # ... ``` -and a final options file that includes these: +And a final options file that includes these: ```yaml title="analysis_options.yaml" include: @@ -415,7 +415,7 @@ include: # ... ``` -then the combined analysis options are computed by applying the options found +Then the combined analysis options are computed by applying the options found in `one.yaml`, then `two.yaml`, then `three.yaml`, and finally `analysis_options.yaml`.