Apply suggestions from code review

Documentation updates

Co-authored-by: Olivier Halligon <olivier.halligon@automattic.com>

bin/pr_changed_files

@@ -6,16 +6,12 @@
 #   pr_changed_files                                  # Check if any files changed
 #   pr_changed_files --all-match <file-patterns...>   # Check if changes are limited to given patterns
 #   pr_changed_files --any-match <file-patterns...>   # Check if changes include files matching patterns
-#   pr_changed_files [--stdout] ...                   # Add --stdout to output "true"/"false" to stdout
+#   pr_changed_files [--stdout] ...                   # Add --stdout to output "true"/"false" to stdout instead of using exit code
 #
-# Exit codes:
-#   0: Condition is met (files changed / patterns matched)
-#   1: Condition is not met (no files changed / patterns not matched)
-# 255: Error in command invocation (bad parameters, not in PR context, etc.)
-#
-# Output:
-#   If the flag --stdout is used, the script will output "true" or "false" to stdout
-#   when the condition is met or not met respectively, and will return exit code 0.
+# Result
+#  - By default, the script exits with code 0 if the condition is met (files changed / patterns matched), 1 if not. This is typically ideal to use in `if` conditions.
+#  - If you use the `--stdout` flag, it will output "true" or "false" instead of using the exit code (and exit 0 in both cases). Useful to assign the result to an environment variable for example.
+#  - The script will exit with code 255 if there is an error in the command invocation (bad parameters, not in PR context, etc.)
 #
 # Typical usage patterns:
 #   # Using exit codes
@@ -28,38 +24,38 @@
 #
 # Behavior:
 #   With no arguments:
-#     Returns exit code 0 (outputs "true") if the PR contains any changes
-#     Returns exit code 1 (outputs "false") if no changes
+#     Returns exit code 0 (or outputs "true" with `--stdout`) if the PR contains any changes
+#     Returns exit code 1 (or outputs "false" with `--stdout`) if no changes
 #
 #   With --all-match:
-#     Returns exit code 0 (outputs "true") if ALL changed files match AT LEAST ONE of the patterns
-#     Returns exit code 1 (outputs "false") if ANY changed file doesn't match ANY pattern
-#     Note: Will return 0 even if not all patterns are matched by the changed files.
+#     Returns exit code 0 (or outputs "true" with `--stdout`) if ALL changed files match AT LEAST ONE of the patterns
+#     Returns exit code 1 (or outputs "false" with `--stdout`) if ANY changed file doesn't match ANY pattern
+#     Note: Will report success even if not all patterns are matched by the changed files.
 #           This mode is especially useful to check if the PR _only_ touches a particular subset of files/folders (but nothing else)
 #
 #   With --any-match:
-#     Returns exit code 0 (outputs "true") if ANY changed file matches ANY of the patterns
-#     Returns exit code 1 (outputs "false") if NONE of the changed files match ANY pattern
-#     Note: Will return 0 even if the PR includes other files not matching the patterns.
+#     Returns exit code 0 (or outputs "true" with `--stdout`) if ANY changed file matches ANY of the patterns
+#     Returns exit code 1 (or outputs "false" with `--stdout`) if NONE of the changed files match ANY pattern
+#     Note: Will report success even if the PR includes other files not matching the patterns.
 #           This mode is especially useful to check if the PR _includes_ (aka _contains at least_) particular files/folders
 #
 # Examples with expected outputs:
 #   # Check if any files changed
 #   $ pr_changed_files
-#   → exit code 0 (outputs "true") if PR has changes
-#   → exit code 1 (outputs "false") if PR has no changes
+#   → exit code 0 if PR has changes
+#   → exit code 1 if PR has no changes
 #
 #   # Check if only documentation files changed (to skip UI tests for example)
 #   $ pr_changed_files --all-match "*.md" "docs/*"
-#   → exit code 0 (outputs "true") if PR only changes `docs/guide.md` and `README.md`
-#   → exit code 0 (outputs "true") if PR only changes `docs/image.png` (not all patterns need to match, ok if no *.md)
-#   → exit code 1 (outputs "false") if PR changes `docs/guide.md` and `src/main.swift` (ALL files need to match at least one pattern)
+#   → exit code 0 if PR only changes `docs/guide.md` and `README.md`
+#   → exit code 0 if PR only changes `docs/image.png` (not all patterns need to match, ok if no *.md)
+#   → exit code 1 if PR changes `docs/guide.md` and `src/main.swift` (ALL files need to match at least one pattern)
 #
 #   # Check if any Swift files changed (to decide if we should run SwiftLint)
 #   $ pr_changed_files --any-match "*.swift" ".swiftlint.yml"
-#   → exit code 0 (outputs "true") if PR changes `src/main.swift` and `README.md` (AT LEAST one file matches one of the patterns)
-#   → exit code 0 (outputs "true") if PR changes `.swiftlint.yml`
-#   → exit code 1 (outputs "false") if PR only changes `README.md` (none of files match any of the patterns)
+#   → exit code 0 if PR changes `src/main.swift` and `README.md` (AT LEAST one file matches one of the patterns)
+#   → exit code 0 if PR changes `.swiftlint.yml`
+#   → exit code 1 if PR only changes `README.md` (none of files match any of the patterns)
 
 if [[ ! "${BUILDKITE_PULL_REQUEST:-invalid}" =~ ^[0-9]+$ ]]; then
     echo "Error: this tool can only be called from a Buildkite PR job" >&2