From f84e735a9a4a304c6c3f4e0122ac39effaf38af8 Mon Sep 17 00:00:00 2001
From: Asher Gomez <ashersaupingomez@gmail.com>
Date: Tue, 17 Sep 2024 14:36:30 +1000
Subject: [PATCH] docs(fs): clarify permissions requirements for
 `exists[Sync]()` (#5983)

* docs(fs): clarify permissions requirements for `exists[Sync]()`

* work
---
 fs/exists.ts | 24 ++++++++++++++++++++++--
 1 file changed, 22 insertions(+), 2 deletions(-)

diff --git a/fs/exists.ts b/fs/exists.ts
index ad9836213..e9f84a3c3 100644
--- a/fs/exists.ts
+++ b/fs/exists.ts
@@ -36,7 +36,8 @@ export interface ExistsOptions {
  * @see {@link https://en.wikipedia.org/wiki/Time-of-check_to_time-of-use} for
  * more information on the time-of-check to time-of-use bug.
  *
- * Requires `--allow-read` and `--allow-sys` permissions.
+ * Requires `--allow-read` permissions, and in some cases, `--allow-sys`
+ * permissions if `options.isReadable` is `true`.
  *
  * @see {@link https://docs.deno.com/runtime/manual/basics/permissions#file-system-access}
  * for more information on Deno's permissions system.
@@ -72,6 +73,9 @@ export interface ExistsOptions {
  * ```
  *
  * @example Check if a path is readable
+ *
+ * Requires `--allow-sys` permissions in some cases.
+ *
  * ```ts no-eval
  * import { exists } from "@std/fs/exists";
  *
@@ -96,6 +100,9 @@ export interface ExistsOptions {
  * ```
  *
  * @example Check if a path is a readable directory
+ *
+ * Requires `--allow-sys` permissions in some cases.
+ *
  * ```ts no-eval
  * import { exists } from "@std/fs/exists";
  *
@@ -104,6 +111,9 @@ export interface ExistsOptions {
  * ```
  *
  * @example Check if a path is a readable file
+ *
+ * Requires `--allow-sys` permissions in some cases.
+ *
  * ```ts no-eval
  * import { exists } from "@std/fs/exists";
  *
@@ -166,7 +176,8 @@ export async function exists(
  * @see {@link https://en.wikipedia.org/wiki/Time-of-check_to_time-of-use} for
  * more information on the time-of-check to time-of-use bug.
  *
- * Requires `--allow-read` and `--allow-sys` permissions.
+ * Requires `--allow-read` permissions, and in some cases, `--allow-sys`
+ * permissions if `options.isReadable` is `true`.
  *
  * @see {@link https://docs.deno.com/runtime/manual/basics/permissions#file-system-access}
  * for more information on Deno's permissions system.
@@ -201,6 +212,9 @@ export async function exists(
  * ```
  *
  * @example Check if a path is readable
+ *
+ * Requires `--allow-sys` permissions in some cases.
+ *
  * ```ts no-eval
  * import { existsSync } from "@std/fs/exists";
  *
@@ -225,6 +239,9 @@ export async function exists(
  * ```
  *
  * @example Check if a path is a readable directory
+ *
+ * Requires `--allow-sys` permissions in some cases.
+ *
  * ```ts no-eval
  * import { existsSync } from "@std/fs/exists";
  *
@@ -233,6 +250,9 @@ export async function exists(
  * ```
  *
  * @example Check if a path is a readable file
+ *
+ * Requires `--allow-sys` permissions in some cases.
+ *
  * ```ts no-eval
  * import { existsSync } from "@std/fs/exists";
  *