Documentation clean up (denoland/deno_std#288)

Original: b699fa67be

colors/test.ts

@@ -2,7 +2,7 @@
 import { test } from "../testing/mod.ts";
 import { assertEquals } from "../testing/asserts.ts";
 import { red, bgBlue, setEnabled, getEnabled } from "./mod.ts";
-import "./example.ts";
+import "../examples/colors.ts";
 
 test(function singleColor() {
   assertEquals(red("Hello world"), "Hello world");

datetime/README.md

@@ -0,0 +1,37 @@
+# datetime
+
+Simple helper to help parse date strings into `Date`, with additionnal functions.
+
+## Usage
+
+### parseDate / parseDateTime
+
+- `parseDate()` - Take an input string and a format to parse the date. Supported formats are exported in `DateFormat`.
+- `parseDateTime()` - Take an input string and a format to parse the dateTime. Supported formats are exported in `DateTimeFormat`.
+
+```ts
+import { parseDate, parseDateTime } from 'https://deno.land/std/datetime/mod.ts'
+
+parseDate("03-01-2019", "dd-mm-yyyy") // output : new Date(2019, 1, 3)
+parseDate("2019-01-03", "yyyy-mm-dd") // output : new Date(2019, 1, 3)
+...
+
+parseDateTime("01-03-2019 16:34", "mm-dd-yyyy hh:mm") // output : new Date(2019, 1, 3, 16, 34)
+parseDateTime("16:34 01-03-2019", "hh:mm mm-dd-yyyy") // output : new Date(2019, 1, 3, 16, 34)
+...
+```
+
+### dayOfYear / currentDayOfYear
+
+- `dayOfYear()` - Returns the number of the day in the year.
+- `currentDayOfYear()` - Returns the number of the current day in the year.
+
+```ts
+import {
+  dayOfYear,
+  currentDayOfYear
+} from "https://deno.land/std/datetime/mod.ts";
+
+dayOfYear(new Date("2019-03-11T03:24:00")); // output: 70
+currentDayOfYear(); // output: ** depends on when you run it :) **
+```

examples/colors.ts

@@ -1,4 +1,4 @@
 // Copyright 2018-2019 the Deno authors. All rights reserved. MIT license.
-import { bgBlue, red, bold, italic } from "./mod.ts";
+import { bgBlue, red, bold, italic } from "../colors/mod.ts";
 
 console.log(bgBlue(italic(red(bold("Hello world!")))));

fs/glob.ts

@@ -20,27 +20,24 @@ export interface GlobOptions {
  * 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.
- * @param glob - Glob pattern to be used
- * @param options - Specific options for the glob pattern
- * @returns A RegExp for the glob pattern
- * @example
- * Looking for all the `ts` files
- * ```typescript
+ * Examples:
+ *
+ *    Looking for all the `ts` files:
  *    walkSync(".", {
  *      match: [glob("*.ts")]
  *    })
- * ```
- * @example
- * Looking for all the `.json` files in any subfolder
- * of the `a` folder
- * ```typescript
+ *
+ *    Looking for all the `.json` files in any subfolder:
  *    walkSync(".", {
  *      match: [glob(join("a", "**", "*.json"),flags: "g",
  *      extended: true,
  *      globstar: true
  *      })]
  *    })
- * ```
+ *
+ * @param glob - Glob pattern to be used
+ * @param options - Specific options for the glob pattern
+ * @returns A RegExp for the glob pattern
  */
 export function glob(glob: string, options: GlobOptions = {}): RegExp {
   return globrex(glob, options).regex;

strings/README.md

@@ -0,0 +1,26 @@
+# Strings
+
+This module provides a few basic utilities to manipulate strings.
+
+## Usage
+
+### pad
+
+Input string is processed to output a string with a minimal length.
+If the parameter `strict` is set to true, the output string length
+is equal to the `strLen` parameter.
+
+Basic usage:
+
+```ts
+import { pad } from "https://deno.land/std/strings/pad.ts";
+pad("deno", 6, { char: "*", side: "left" }) // output : "**deno"
+pad("deno", 6, { char: "*", side: "right"}) // output : "deno**"
+pad("denosorusrex", 6 {
+    char: "*",
+    side: "left",
+    strict: true,
+    strictSide: "right",
+    strictChar: "..."
+}) // output : "den..."
+```

testing/README.md

@@ -9,7 +9,7 @@ The module exports a `test` function which is the test harness in Deno. It
 accepts either a function (including async functions) or an object which
 contains a `name` property and a `fn` property. When running tests and
 outputting the results, the name of the past function is used, or if the
-object is passed, the `name` property is used to identify the test.
+object is passed, the `name` property is used to identify the test. If the assertion is false an `AssertionError` will be thrown.
 
 Asserts are exposed in `testing/asserts.ts` module.
 
@@ -18,8 +18,13 @@ Asserts are exposed in `testing/asserts.ts` module.
 - `assert()` - Expects a boolean value, throws if the value is `false`.
 - `assertEquals()` - Uses the `equal` comparison and throws if the `actual` and
   `expected` are not equal.
+- `assertNotEquals()` - Uses the `equal` comparison and throws if the `actual` and
+  `expected` are equal.
 - `assertStrictEq()` - Compares `actual` and `expected` strictly, therefore
   for non-primitives the values must reference the same instance.
+- `assertStrContains()` - Make an assertion that `actual` contains `expected`.
+- `assertMatch()` - Make an assertion that `actual` match RegExp `expected`.
+- `assertArrayContains()` - Make an assertion that `actual` array contains the `expected` values.
 - `assertThrows()` - Expects the passed `fn` to throw. If `fn` does not throw,
   this function does. Also compares any errors thrown to an optional expected
   `Error` class and checks that the error `.message` includes an optional
@@ -29,6 +34,8 @@ Asserts are exposed in `testing/asserts.ts` module.
   function will throw asynchronously. Also compares any errors thrown to an
   optional expected `Error` class and checks that the error `.message` includes
   an optional string.
+- `unimplemented()` - Use this to stub out methods that will throw when invoked
+- `unreachable()` - Used to assert unreachable code
 
 `runTests()` executes the declared tests.