Docs: More

Author: adrien-berchet

README.md

@@ -36,7 +36,7 @@ the files, so it is not able to report which values are different.
 
 ### Compare two directories
 
-If one wants to compare two directories with the following structures:
+Let's compare two directories with the following structures:
 
 ```bash
 └── reference_dir
@@ -55,6 +55,9 @@ If one wants to compare two directories with the following structures:
     └── file_1.c
 ```
 
+The `reference` directory contains all the files that should be checked in the `compared` directory,
+which means that extraneous files in the `compared` directory are just ignored.
+
 These two directories can be compared with the following code:
 
 ```python
@@ -63,10 +66,15 @@ import dir_content_diff
 dir_content_diff.compare_trees("reference_dir", "compared_dir")
 ```
 
+> [!WARNING]
+> The order of the parameters is important: the first path is considered as the `reference`
+> directory while the second one is the `compared` directory. Inverting the parameters way return
+> a different result (in this example it would return that the file `sub_file_3.b` is missing).
+
 If all the files are identical, this code will return an empty dictionary because no difference
-was detected. This is because `dir-content-diff` is only looking for files in the compared directory
-that are also present in the reference directory. Thus extraneous files from the compared directory
-are not considered.
+was detected. As pointed previously, this is because `dir-content-diff` is only looking for files
+in the compared directory that are also present in the reference directory, so the file
+`sub_file_3.b` is just ignored in this case.
 
 If ``reference_dir/file_1.c`` is the following JSON-like file: