Chmod API documentation improvements (#4427)

1 files changed, 24 insertions, 0 deletions

diff --git a/cli/js/lib.deno.ns.d.ts b/cli/js/lib.deno.ns.d.ts
index 3ebd5bc9d..ac52bb9a3 100644
--- a/cli/js/lib.deno.ns.d.ts
+++ b/cli/js/lib.deno.ns.d.ts
@@ -948,6 +948,10 @@ declare namespace Deno {
    *
    *       Deno.chmodSync("/path/to/file", 0o666);
    *
+   * For a full description, see [chmod](#chmod)
+   *
+   * NOTE: This API currently has no effect on Windows
+   *
    * Requires `allow-write` permission. */
   export function chmodSync(path: string, mode: number): void;
 
@@ -956,6 +960,26 @@ declare namespace Deno {
    *
    *       await Deno.chmod("/path/to/file", 0o666);
    *
+   * The mode is a sequence of 3 octal numbers.  The first/left-most number
+   * specifies the permissions for the owner.  The second number specifies the
+   * permissions for the group. The last/right-most number specifies the
+   * permissions for others.  For example, with a mode of 0o764, the owner (7) can
+   * read/write/execute, the group (6) can read/write and everyone else (4) can
+   * read only.
+   *
+   * | Number | Description |
+   * | ------ | ----------- |
+   * | 7      | read, write, and execute |
+   * | 6      | read and write |
+   * | 5      | read and execute |
+   * | 4      | read only |
+   * | 3      | write and execute |
+   * | 2      | write only |
+   * | 1      | execute only |
+   * | 0      | no permission |
+   *
+   * NOTE: This API currently has no effect on Windows
+   *
    * Requires `allow-write` permission. */
   export function chmod(path: string, mode: number): Promise<void>;