From efdcf34b79708e90bd142084e5f2f83021871287 Mon Sep 17 00:00:00 2001
From: Austin L Wolfgram <austinwolfy@gmail.com>
Date: Sun, 6 Apr 2025 20:00:18 +0200
Subject: [PATCH] Fix out of date comments on merge_toml_values (#13253)

merge_toplevel_arrays is no longer a parameter for this method, and the
example fits better in a doc comment.
---
 helix-loader/src/config.rs | 16 --------------
 helix-loader/src/lib.rs    | 44 +++++++++++++++++++++++++-------------
 2 files changed, 29 insertions(+), 31 deletions(-)

diff --git a/helix-loader/src/config.rs b/helix-loader/src/config.rs
index d092d20f7..1f414de67 100644
--- a/helix-loader/src/config.rs
+++ b/helix-loader/src/config.rs
@@ -23,22 +23,6 @@ pub fn user_lang_config() -> Result<toml::Value, toml::de::Error> {
     .collect::<Result<Vec<_>, _>>()?
     .into_iter()
     .fold(default_lang_config(), |a, b| {
-        // combines for example
-        // b:
-        //   [[language]]
-        //   name = "toml"
-        //   language-server = { command = "taplo", args = ["lsp", "stdio"] }
-        //
-        // a:
-        //   [[language]]
-        //   language-server = { command = "/usr/bin/taplo" }
-        //
-        // into:
-        //   [[language]]
-        //   name = "toml"
-        //   language-server = { command = "/usr/bin/taplo" }
-        //
-        // thus it overrides the third depth-level of b with values of a if they exist, but otherwise merges their values
         crate::merge_toml_values(a, b, 3)
     });
 
diff --git a/helix-loader/src/lib.rs b/helix-loader/src/lib.rs
index ae9ffe550..54980dd7d 100644
--- a/helix-loader/src/lib.rs
+++ b/helix-loader/src/lib.rs
@@ -154,17 +154,36 @@ pub fn default_log_file() -> PathBuf {
 
 /// Merge two TOML documents, merging values from `right` onto `left`
 ///
-/// When an array exists in both `left` and `right`, `right`'s array is
-/// used. When a table exists in both `left` and `right`, the merged table
-/// consists of all keys in `left`'s table unioned with all keys in `right`
-/// with the values of `right` being merged recursively onto values of
-/// `left`.
+/// `merge_depth` sets the nesting depth up to which values are merged instead
+/// of overridden.
 ///
-/// `merge_toplevel_arrays` controls whether a top-level array in the TOML
-/// document is merged instead of overridden. This is useful for TOML
-/// documents that use a top-level array of values like the `languages.toml`,
-/// where one usually wants to override or add to the array instead of
-/// replacing it altogether.
+/// When a table exists in both `left` and `right`, the merged table consists of
+/// all keys in `left`'s table unioned with all keys in `right` with the values
+/// of `right` being merged recursively onto values of `left`.
+///
+/// `crate::merge_toml_values(a, b, 3)` combines, for example:
+///
+/// b:
+/// ```toml
+/// [[language]]
+/// name = "toml"
+/// language-server = { command = "taplo", args = ["lsp", "stdio"] }
+/// ```
+/// a:
+/// ```toml
+/// [[language]]
+/// language-server = { command = "/usr/bin/taplo" }
+/// ```
+///
+/// into:
+/// ```toml
+/// [[language]]
+/// name = "toml"
+/// language-server = { command = "/usr/bin/taplo" }
+/// ```
+///
+/// thus it overrides the third depth-level of b with values of a if they exist,
+/// but otherwise merges their values
 pub fn merge_toml_values(left: toml::Value, right: toml::Value, merge_depth: usize) -> toml::Value {
     use toml::Value;
 
@@ -174,11 +193,6 @@ pub fn merge_toml_values(left: toml::Value, right: toml::Value, merge_depth: usi
 
     match (left, right) {
         (Value::Array(mut left_items), Value::Array(right_items)) => {
-            // The top-level arrays should be merged but nested arrays should
-            // act as overrides. For the `languages.toml` config, this means
-            // that you can specify a sub-set of languages in an overriding
-            // `languages.toml` but that nested arrays like Language Server
-            // arguments are replaced instead of merged.
             if merge_depth > 0 {
                 left_items.reserve(right_items.len());
                 for rvalue in right_items {