Merge pull request #24 from jfy133/docs-fixes

Improve user eligibility for getAllFilesInDir() docs

docs/usage.md

@@ -64,7 +64,14 @@ The first argument is path to the YAML file, the second and third arguments are
 
 ## `getAllFilesFromDir()`
 
-This function generates a list of all the contents within a directory, allowing for the exclusion of specific files using a glob pattern. It can be used to obtain filenames alone, enabling snapshotting of just the names when the content is not stable. Alternatively, it can snapshot the entire list of files with stable content.
+This function generates a list of all the contents within a directory (and subdirectories), additionally allowing for the inclusion or exclusion of specific files using glob patterns.
+
+- The first argument is the directory path to screen for file paths (e.g. a  pipeline’s `outdir` ).
+- The second argument is a boolean indicating whether to include subdirectory names in the list.
+- The third argument is a _list_ of glob patterns to exclude.
+- The fourth argument is a _file_ containing additional glob patterns to exclude.
+- The fifth argument is a _list_ of glob patterns to include.
+- The sixth argument is a boolean indicating whether to output relative paths.
 
 In this example, below are the files produced by a pipeline:
 
@@ -79,31 +86,36 @@ results/
 2 directories, 3 files
 ```
 
-In this example, 1 file is stable with stable content (`stable_content.txt`), and 1 file is stable with a stable name (`stable_name.txt`).
-The last file has no stable content (`execution_trace_2024-09-30_13-10-16.txt`) as its name is based on the date and time of the pipeline execution.
+One file has stable content and a stable name (`stable_content.txt`), and one file has unstable contents but a stable name (`stable_name.txt`).
+The last file (`execution_trace_2024-09-30_13-10-16.txt`) has no stable content nor a stable name, as its name is based on the date and time of the pipeline execution.
+
+We aim to snapshot files with stable content, and stable names (for both files and directories), but excluding the completely unstable file.
+
+First, we will specify the following two variables that we will pass to the nf-test snapshot function:
+
+- The `stable_name` variable contains a list of all files and directories, excluding those matching the glob pattern `pipeline_info/execution_*.{html,txt}` (i.e., the unstable file).
+- The `stable_content` variable contains a list of all files, excluding those that match the two glob patterns: `pipeline_info/execution_*.{html,txt}` and `**/stable_name.txt`.
+  - The latter is specified in the `tests/getAllFilesFromDir/.nftignore` file.
+
+```groovy
+def stable_name    = getAllFilesFromDir(params.outdir, true, ['pipeline_info/execution_*.{html,txt}'], null, ['*', '**/*'])
+def stable_content = getAllFilesFromDir(params.outdir, false, ['pipeline_info/execution_*.{html,txt}'], 'tests/getAllFilesFromDir/.nftignore', ['*', '**/*'])
+```
 
-In this example, we aim to snapshot files with stable content, along with the names of files and folders that are stable.
+Secondly, we need to supply these two variables to the nf-test snapshot assrtion.
+The list of files in `stable_content` can be supplied to the snapshot directly, and nf-test will include the md5sum hash of the file contents.
+For the list of stable file names with unstable contents, we can use `stable_name*.name`, to just extract just _name_ of every file in the list for comparison (i.e., without generating the md5sum hash).
 
-•`stable_name` is a list of all files and folders, excluding those matching the glob pattern `pipeline_info/execution_*.{html,txt}`.
-•`stable_content` is a list of all files, excluding those that match the two glob patterns: `pipeline_info/execution_*.{html,txt}` and `**/stable_name.txt`. The latter is specified in the `tests/getAllFilesFromDir/.nftignore` file.
-By using `stable_name*.name`, we extract the name of every file in `stable_name` and add them to the snapshot.
-`stable_content` can be used in the snapshot directly to include the hash of the file contents.
 
 ```groovy
 def stable_name    = getAllFilesFromDir(params.outdir, true, ['pipeline_info/execution_*.{html,txt}'], null, ['*', '**/*'])
 def stable_content = getAllFilesFromDir(params.outdir, false, ['pipeline_info/execution_*.{html,txt}'], 'tests/getAllFilesFromDir/.nftignore', ['*', '**/*'])
 assert snapshot(
-  stable_name*.name,
   stable_content
+  stable_name*.name,
 ).match()
 ```
 
-• The first argument is the pipeline’s `outdir` directory path.
-• The second argument is a boolean indicating whether to include folders.
-• The third argument is a list of glob patterns to ignore.
-• The fourth argument is a file containing additional glob patterns to ignore.
-• The fifth argument is a list of glob patterns to include.
-
 `getAllFilesFromDir()` also supports named parameters:
 
 ```groovy