From 5d1c555728fd9537e349d8807098e10ca0b56f1b Mon Sep 17 00:00:00 2001
From: "Yu-Hsiang M. Tsai" <yhmtsai@gmail.com>
Date: Thu, 13 Feb 2025 17:20:11 +0100
Subject: [PATCH] update docuementation

Co-authored-by: Marcel Koch <marcel.koch@kit.edu>
---
 extensions/test/config/CMakeLists.txt         |  4 +++
 extensions/test/config/yaml_config.cpp        |  2 +-
 .../ginkgo/extensions/config/yaml_config.hpp  | 26 +++++++++++++++----
 3 files changed, 26 insertions(+), 6 deletions(-)

diff --git a/extensions/test/config/CMakeLists.txt b/extensions/test/config/CMakeLists.txt
index 9a8f7ce267c..377971dfeb3 100644
--- a/extensions/test/config/CMakeLists.txt
+++ b/extensions/test/config/CMakeLists.txt
@@ -20,16 +20,20 @@ configure_file(
 configure_file(
     test.json
     "${Ginkgo_BINARY_DIR}/extensions/test/config/test.json"
+    COPYONLY
 )
 configure_file(
     test.yaml
     "${Ginkgo_BINARY_DIR}/extensions/test/config/test.yaml"
+    COPYONLY
 )
 configure_file(
     alias.yaml
     "${Ginkgo_BINARY_DIR}/extensions/test/config/alias.yaml"
+    COPYONLY
 )
 configure_file(
     nested_alias.yaml
     "${Ginkgo_BINARY_DIR}/extensions/test/config/nested_alias.yaml"
+    COPYONLY
 )
diff --git a/extensions/test/config/yaml_config.cpp b/extensions/test/config/yaml_config.cpp
index 2e86127de39..ab71bb175d2 100644
--- a/extensions/test/config/yaml_config.cpp
+++ b/extensions/test/config/yaml_config.cpp
@@ -1,4 +1,4 @@
-// SPDX-FileCopyrightText: 2017 - 2024 The Ginkgo authors
+// SPDX-FileCopyrightText: 2017 - 2025 The Ginkgo authors
 //
 // SPDX-License-Identifier: BSD-3-Clause
 
diff --git a/include/ginkgo/extensions/config/yaml_config.hpp b/include/ginkgo/extensions/config/yaml_config.hpp
index b7dfd07a593..e73a9f02dc4 100644
--- a/include/ginkgo/extensions/config/yaml_config.hpp
+++ b/include/ginkgo/extensions/config/yaml_config.hpp
@@ -1,4 +1,4 @@
-// SPDX-FileCopyrightText: 2017 - 2024 The Ginkgo authors
+// SPDX-FileCopyrightText: 2017 - 2025 The Ginkgo authors
 //
 // SPDX-License-Identifier: BSD-3-Clause
 
@@ -20,7 +20,7 @@ namespace config {
 
 
 /**
- * parse_yaml takes the yaml-cpp node object to generate the property tree
+ * parse_yaml takes a yaml-cpp node object to generate the property tree
  * object
  */
 inline gko::config::pnode parse_yaml(const YAML::Node& input)
@@ -56,7 +56,6 @@ inline gko::config::pnode parse_yaml(const YAML::Node& input)
                                        YAML::Dump(it->second));
                 }
             } else {
-                std::string content = it->first.as<std::string>();
                 nodes[key] = parse_yaml(it->second);
             }
         }
@@ -97,8 +96,25 @@ inline gko::config::pnode parse_yaml(const YAML::Node& input)
  * parse_yaml_file takes the yaml file to generate the property tree object
  *
  * @note Because YAML always needs a entry for reusing, there will be more than
- * one entry when putting the anchors in the top level. This function can not
- * know which entry is the actual solver, so please use the parse_yaml function.
+ * one entry when putting the anchors in the top level. It is unclear which
+ * entry is the actual solver to parse, so please use the parse_yaml function
+ * and specify the actual entry.
+ *
+ * for example,
+ * ```
+ * reuse: &reuse_config
+ *   ...
+ * actual:
+ *   << *reuse
+ *   ...
+ * ```
+ * when passing the file to this function, `reuse` and `actual` are valid
+ * entries such that we can not randomly pick one as solver.
+ * ```
+ *   // yaml is the object from the file
+ *   auto solver_factory = parse_yaml(yaml["actual"]);
+ * ```
+ * By doing so, we know the `actual` entry is the solver to parse.
  */
 inline gko::config::pnode parse_yaml_file(std::string filename)
 {