[clang-format] Add option to remove leading blank lines (#91221)

The options regarding which blank lines are kept are also aggregated.
The new option is `KeepEmptyLines`.

This patch was initially part of 9267f8f19a2e502e.  I neglected to check
the server builds before I added it.  It broke clangd.  Jie Fu fixed the
problem in 4c91b49bab0728d4.  I was unaware of it.  I thought the main
branch was still broken.  I reverted the first patch in
70cfece24d6cbb57.  It broke his fix.  He reverted it in
c69ea04fb9738db2.  Now the feature is added again including the fix.

2 files changed, 40 insertions, 10 deletions

diff --git a/clang/docs/ClangFormatStyleOptions.rst b/clang/docs/ClangFormatStyleOptions.rst
index bb00c209..080cba9 100644
--- a/clang/docs/ClangFormatStyleOptions.rst
+++ b/clang/docs/ClangFormatStyleOptions.rst
@@ -4443,23 +4443,51 @@ the configuration (without a prefix: ``Auto``).
      false:
      import {VeryLongImportsAreAnnoying, VeryLongImportsAreAnnoying, VeryLongImportsAreAnnoying,} from "some/module.js"
 
+.. _KeepEmptyLines:
+
+**KeepEmptyLines** (``KeepEmptyLinesStyle``) :versionbadge:`clang-format 19` :ref:`¶ <KeepEmptyLines>`
+  Which empty lines are kept.  See ``MaxEmptyLinesToKeep`` for how many
+  consecutive empty lines are kept.
+
+  Nested configuration flags:
+
+  Options regarding which empty lines are kept.
+
+  For example, the config below will remove empty lines at start of the
+  file, end of the file, and start of blocks.
+
+
+  .. code-block:: c++
+
+    KeepEmptyLines:
+      AtEndOfFile: false
+      AtStartOfBlock: false
+      AtStartOfFile: false
+
+  * ``bool AtEndOfFile`` Keep empty lines at end of file.
+
+  * ``bool AtStartOfBlock`` Keep empty lines at start of a block.
+
+    .. code-block:: c++
+
+       true:                                  false:
+       if (foo) {                     vs.     if (foo) {
+                                                bar();
+         bar();                               }
+       }
+
+  * ``bool AtStartOfFile`` Keep empty lines at start of file.
+
+
 .. _KeepEmptyLinesAtEOF:
 
 **KeepEmptyLinesAtEOF** (``Boolean``) :versionbadge:`clang-format 17` :ref:`¶ <KeepEmptyLinesAtEOF>`
-  Keep empty lines (up to ``MaxEmptyLinesToKeep``) at end of file.
+  This option is deprecated. See ``AtEndOfFile`` of ``KeepEmptyLines``.
 
 .. _KeepEmptyLinesAtTheStartOfBlocks:
 
 **KeepEmptyLinesAtTheStartOfBlocks** (``Boolean``) :versionbadge:`clang-format 3.7` :ref:`¶ <KeepEmptyLinesAtTheStartOfBlocks>`
-  If true, the empty line at the start of blocks is kept.
-
-  .. code-block:: c++
-
-     true:                                  false:
-     if (foo) {                     vs.     if (foo) {
-                                              bar();
-       bar();                               }
-     }
+  This option is deprecated. See ``AtStartOfBlock`` of ``KeepEmptyLines``.
 
 .. _LambdaBodyIndentation:
 
diff --git a/clang/docs/ReleaseNotes.rst b/clang/docs/ReleaseNotes.rst
index feba3c7..35d2509 100644
--- a/clang/docs/ReleaseNotes.rst
+++ b/clang/docs/ReleaseNotes.rst
@@ -1112,6 +1112,8 @@ clang-format
 - Adds ``AllowShortCaseExpressionOnASingleLine`` option.
 - Adds ``AlignCaseArrows`` suboption to ``AlignConsecutiveShortCaseStatements``.
 - Adds ``LeftWithLastLine`` suboption to ``AlignEscapedNewlines``.
+- Adds ``KeepEmptyLines`` option to deprecate ``KeepEmptyLinesAtEOF``
+  and ``KeepEmptyLinesAtTheStartOfBlocks``.
 
 libclang
 --------