update docs regarding argument handling (yaml, func_args)

docs/reference/declarative_usage.md

@@ -4,9 +4,12 @@
 Configure your experiments using a YAML file, which serves as a central reference for setting up your project.
 This approach simplifies sharing, reproducing and modifying configurations.
 
-!!! note
-    You can partially define arguments in the YAML file and partially provide the arguments directly to `neps.run`.
-    However, double referencing is not allowed. You cannot define the same argument in both places.
+!!! note "Argument Handling and Prioritization"
+    You can partially define and provide arguments via `run_args` (YAML file) and partially provide the arguments
+    directly to `neps.run`. Arguments directly provided to `neps.run` get prioritized over those defined in the YAML file. An exception to this
+    is for `searcher_kwargs` where a merge happens between the configurations. In this case, the directly provided arguments
+    are still prioritized, but the values from both the directly provided arguments and the YAML file are merged.
+
 
 #### Simple YAML Example
 Below is a straightforward YAML configuration example for NePS covering the required arguments.

neps/utils/run_args.py

@@ -543,6 +543,7 @@ def __init__(self, func_args: dict, yaml_args: str | Default | None = None):
                 else:
                     dict_settings[key] = value
 
+        # drop run_args, not needed as a setting attribute
         del dict_settings[RUN_ARGS]
         self.assign(dict_settings)
         self.check()
@@ -551,6 +552,8 @@ def merge(self, func_args: dict, yaml_args: dict) -> dict:
         """Merge func_args and yaml_args. func_args gets priority over yaml_args."""
         # Initialize with YAML settings
         merged_settings = yaml_args.copy()
+
+        # overwrite or merge keys
         for key, value in func_args.items():
             # Handle searcher_kwargs for BaseOptimizer case
             if key == SEARCHER_KWARGS: