From 92805672c3703c43481103bd1e81b12844a87b74 Mon Sep 17 00:00:00 2001
From: Josh Triplett <josh@joshtriplett.org>
Date: Thu, 22 Jun 2023 12:41:30 -0700
Subject: [PATCH] style-guide: Move and expand text about trailing commas

`principles.md` includes some high-level guiding principles for
formatting, but also includes a few specific formatting provisions.
While those provisions apply in many places, the same holds true for
other high-level guidance. Move the text about trailing commas to
`README.md`, so that `principles.md` can focus on guiding principles
while the top level of the style guide gives concrete formatting
recommendations.
---
 src/doc/style-guide/src/README.md     | 21 +++++++++++++++++++++
 src/doc/style-guide/src/principles.md |  7 -------
 2 files changed, 21 insertions(+), 7 deletions(-)

diff --git a/src/doc/style-guide/src/README.md b/src/doc/style-guide/src/README.md
index 49a4bce2f5dcd..3d47e33841a54 100644
--- a/src/doc/style-guide/src/README.md
+++ b/src/doc/style-guide/src/README.md
@@ -49,6 +49,27 @@ a_function_call(foo,
 This makes for smaller diffs (e.g., if `a_function_call` is renamed in the above
 example) and less rightward drift.
 
+### Trailing commas
+
+Lists should have a trailing comma when followed by a newline:
+
+```rust
+function_call(
+    argument,
+    another_argument,
+);
+
+let array = [
+    element,
+    another_element,
+    yet_another_element,
+];
+```
+
+This makes moving code (e.g., by copy and paste) easier, and makes diffs
+smaller, as appending or removing items does not require modifying another line
+to add or remove a comma.
+
 ### Blank lines
 
 Separate items and statements by either zero or one blank lines (i.e., one or
diff --git a/src/doc/style-guide/src/principles.md b/src/doc/style-guide/src/principles.md
index c3104e6d9b60f..c86121e6a4697 100644
--- a/src/doc/style-guide/src/principles.md
+++ b/src/doc/style-guide/src/principles.md
@@ -27,10 +27,3 @@ following principles (in rough priority order):
     - ease of implementation (in Rustfmt, and in other tools/editors/code generators)
     - internal consistency
     - simplicity of formatting rules
-
-
-## Overarching guidelines
-
-Lists should have a trailing comma when followed by a newline, see the block
-indent example above. This choice makes moving code (e.g., by copy and paste)
-easier and makes smaller diffs.