docs:documented trailing_commas (#7122)

fixes #7101 

Changes made:
Restructured the configuration section - Changed the heading from
"Configuring formatter page width" to "Configuring the formatter" with
subheadings for "Page width" and "Preserving trailing commas"

Added documentation for trailing_commas: preserve

@parlough @jonasfj @conooi @antfitch  please review

---------

Co-authored-by: Connie Ooi <connieooi@google.com>

Author: Anushreebasics

src/content/effective-dart/style.md

@@ -525,7 +525,7 @@ an import or export), it may remain whole even if it causes the line to go over
 because newlines are significant inside the string and splitting the lines into
 shorter ones can alter the program.
 
-[configure]: /tools/dart-format#configuring-formatter-page-width
+[configure]: /tools/dart-format#page-width
 
 <a id="do-use-curly-braces-for-all-flow-control-structures"></a>
 ### DO use curly braces for all flow control statements

src/content/resources/whats-new.md

@@ -252,7 +252,7 @@ we made the following changes to this site:
 [inference using bounds]: /language/type-system/#type-argument-inference
 [for example]: /tools/linter-rules/annotate_overrides
 [Bluesky]: https://bsky.app/profile/dart.dev
-[configurable line length]: /tools/dart-format#configuring-formatter-page-width
+[configurable line length]: /tools/dart-format#page-width
 [shared analysis options]: /tools/analysis#including-shared-options
 [line length]: /effective-dart/style#prefer-lines-80-characters-or-fewer
 [stray files]: /tools/pub/workspaces#stray-files

src/content/tools/analysis.md

@@ -671,5 +671,5 @@ Use the following resources to learn more about static analysis in Dart:
 [disable individual rules]: #disabling-individual-rules
 [Effective Dart]: /effective-dart
 [`dart format`]: /tools/dart-format
-[Configuring formatter page width]: /tools/dart-format#configuring-formatter-page-width
+[Configuring formatter page width]: /tools/dart-format#page-width
 [Troubleshoot analyzer performance]: /tools/analyzer-performance

src/content/tools/dart-format.md

@@ -106,13 +106,16 @@ that splits across multiple lines, and removes them from ones that don't.
 To learn more about best practices for writing and styling Dart code,
 check out the [Dart style guide][].
 
-### Configuring formatter page width
+### Configure the formatter
 
 When you run `dart format`, the formatter defaults to
 80 character line length or shorter. 
-If you'd like to configure the line length for your project,
-you can add a top-level `formatter` section to the
-[`analysis_options.yaml`][] file, like so:
+Configure the formatter's behavior by adding a top-level
+`formatter` section to the [`analysis_options.yaml`][] file.
+
+#### Page width
+
+Configure the line length for your project:
 
 ```yaml title="analysis_options.yaml"
 formatter:
@@ -122,17 +125,36 @@ formatter:
 With the analysis options file typically at the root,
 the configured line length will apply to everything in the package.
 
-You can also configure individual files' line length,
-overriding the analysis options file,
-with a marker comment at the top of the file before any other code:
+#### Preserve trailing commas
+
+By default, `dart format` adds or removes trailing commas
+based on whether the construct splits across multiple lines.
+To force a construct to split even when it fits on one line,
+configure the formatter to preserve trailing commas:
+
+```yaml title="analysis_options.yaml"
+formatter:
+  trailing_commas: preserve
+```
+
+When enabled, adding a trailing comma to an argument list,
+parameter list, or other constructs, forces the formatter to split 
+it across multiple lines, even if it fits on one line. This provides 
+manual control over line breaks for specific constructs.
+This gives you manual control over line breaks for specific constructs.
+
+Configure an individual file's line length,
+overriding the analysis options, by adding 
+a marker comment at the top of the file, before any other code:
 
 ```dart
 // dart format width=123
 ```
 
 :::version-note
-Configurable page width requires
+Configurable formatter options require
 a [language version][] of at least 3.7.
+The `trailing_commas` option requires at least 3.8.
 :::
 
 ## Learn more