From 4d25cc1e355e19a6534f403587b84ba9d67652f5 Mon Sep 17 00:00:00 2001
From: Vincent LE GOFF <g_n_s@hotmail.fr>
Date: Sat, 13 Apr 2019 21:30:56 +0200
Subject: [PATCH] doc: Add missing documentation (#336)

---
 README.md    |  17 ++++++
 fs/README.md | 152 +++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 169 insertions(+)
 create mode 100644 fs/README.md

diff --git a/README.md b/README.md
index bd1b0ff3fb..90e31e7995 100644
--- a/README.md
+++ b/README.md
@@ -18,6 +18,23 @@ It's strongly recommended that you link to tagged releases rather than the
 master branch. The project is still young and we expect disruptive renames in
 the future.
 
+## Documentation
+
+Here are the dedicated documentations of modules:
+
+- [colors](colors/README.md)
+- [datetime](datetime/README.md)
+- [examples](examples/README.md)
+- [flags](flags/README.md)
+- [fs](fs/README.md)
+- [http](http/README.md)
+- [log](log/README.md)
+- [media_types](media_types/README.md)
+- [prettier](prettier/README.md)
+- [strings](strings/README.md)
+- [testing](testing/README.md)
+- [toml](toml/README.md)
+
 ## Contributing
 
 Follow the [style guide](https://deno.land/style_guide.html).
diff --git a/fs/README.md b/fs/README.md
new file mode 100644
index 0000000000..ad02199ccb
--- /dev/null
+++ b/fs/README.md
@@ -0,0 +1,152 @@
+# fs
+
+fs module is made to provide helpers to manipulate the filesystem.
+
+## Usage
+
+All the following modules are exposed in `mod.ts`
+
+### emptyDir
+
+Ensures that a directory is empty. Deletes directory contents if the directory is not empty.
+If the directory does not exist, it is created.
+The directory itself is not deleted.
+
+```ts
+import { emptyDir, emptyDirSync } from "https://deno.land/std/fs/mod.ts";
+
+emptyDir("./foo"); // returns a promise
+emptyDirSync("./foo"); // void
+```
+
+### ensureDir
+
+Ensures that the directory exists.
+If the directory structure does not exist, it is created. Like mkdir -p.
+
+```ts
+import { ensureDir, ensureDirSync } from "https://deno.land/std/fs/mod.ts";
+
+ensureDir("./bar"); // returns a promise
+ensureDirSync("./ensureDirSync"); // void
+```
+
+### ensure_file
+
+Ensures that the file exists.
+If the file that is requested to be created is in directories
+that do not exist, these directories are created.
+If the file already exists, it is **NOT MODIFIED**.
+
+```ts
+import { ensureFile, ensureFileSync } from "https://deno.land/std/fs/mod.ts";
+
+ensureFile("./folder/targetFile.dat"); // returns promise
+ensureFileSync("./folder/targetFile.dat"); // void
+```
+
+### eol
+
+Detects and format the passed string for the targeted End Of Line character.
+
+```ts
+import { format, detect, EOL } from "https://deno.land/std/fs/mod.ts";
+
+const CRLFinput = "deno\r\nis not\r\nnode";
+const Mixedinput = "deno\nis not\r\nnode";
+const LFinput = "deno\nis not\nnode";
+const NoNLinput = "deno is not node";
+
+detect(LFinput); // output EOL.LF
+detect(CRLFinput); // output EOL.CRLF
+detect(Mixedinput); // output EOL.CRLF
+detect(NoNLinput); // output null
+
+format(CRLFinput, EOL.LF); // output "deno\nis not\nnode"
+...
+```
+
+### exists
+
+Test whether or not the given path exists by checking with the file system
+
+```ts
+import { exists, existsSync } from "https://deno.land/std/fs/mod.ts";
+
+exists("./foo"); // returns a Promise<boolean>
+existsSync("./foo"); // returns boolean
+```
+
+### glob
+
+Generate a regex based on glob pattern and options
+This was meant to be using the the `fs.walk` function
+but can be used anywhere else.
+
+```ts
+import { glob } from "https://deno.land/std/fs/mod.ts";
+
+glob("foo/**/*.json", {
+  flags: "g",
+  extended: true,
+  globstar: true
+}); // returns the regex to find all .json files in the folder foo
+```
+
+### move
+
+Moves a file or directory. Overwrites it if option provided
+
+```ts
+import { move, moveSync } from "https://deno.land/std/fs/mod.ts";
+
+move("./foo", "./bar"); // returns a promise
+moveSync("./foo", "./bar"); // void
+moveSync("./foo", "./existingFolder", { overwrite: true });
+// Will overwrite existingFolder
+```
+
+### readJson
+
+Reads a JSON file and then parses it into an object
+
+```ts
+import { readJson, readJsonSync } from "https://deno.land/std/fs/mod.ts";
+
+const f = await readJson("./foo.json");
+const foo = readJsonSync("./foo.json");
+```
+
+### walk
+
+Iterate all files in a directory recursively.
+
+```ts
+import { walk, walkSync } from "https://deno.land/std/fs/mod.ts";
+
+for (const fileInfo of walkSync()) {
+  console.log(fileInfo.path);
+}
+
+// Async
+for (const fileInfo of walk()) {
+  console.log(fileInfo.path);
+}
+```
+
+### writejson
+
+Writes an object to a JSON file.
+
+**WriteJsonOptions**
+
+- replacer : An array of strings and numbers that acts as a approved list for selecting the object properties that will be stringified.
+- space : Adds indentation, white space, and line break characters to the return-value JSON text to make it easier to read.
+
+```ts
+import { writeJson, writeJsonSync } from "https://deno.land/std/fs/mod.ts";
+
+writeJson("./target.dat", { foo: "bar" }, { spaces: 2 }); // returns a promise
+writeJsonSync("./target.dat", { foo: "bar" }, { replacer: ["foo"] });
+// void
+```