From 854f55e987466044f5532d59ef1c7d453c81756a Mon Sep 17 00:00:00 2001
From: Gadi Cohen <dragon@wastelands.net>
Date: Fri, 12 Feb 2021 12:47:08 +0200
Subject: [PATCH] chore(docs): refactor modules, add info on validation, errors
 [skip ci]

---
 docs/README.md | 66 ++++++++++++++++++++++++++++++++++++++------------
 1 file changed, 51 insertions(+), 15 deletions(-)

diff --git a/docs/README.md b/docs/README.md
index dbe7cef9..14f7a3ca 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -3,17 +3,8 @@
 ## Table of Contents
 
 1. [Common Options](#common-options)
-
-1. Modules
-    1. [autoc](./modules/autoc.md)
-    1. [historical](./modules/historical.md)
-    1. [quote](./modules/quote.md)
-    1. [quoteSummary](./modules/quoteSummary.md)
-    1. [search](./modules/search.md)
-    1. [recommendationsBySymbol](./modules/recommendationsBySymbol.md)
-
-1. [Errors Handling](#error-handling)
-
+1. [Modules](#modules)
+1. [Error Handling](#error-handling)
 1. [Validation](./validation.md)
 
 <a name="common-options"></a>
@@ -33,15 +24,60 @@ const moduleOpts = {
 const result = await yahooFinance.module(query, queryOpts, moduleOpts);
 ```
 
+<a name="modules"></a>
+## Modules
 
+1. [autoc](./modules/autoc.md) - autocomplete, great for symbol lookup.
+1. [historical](./modules/historical.md) - historical market prices.
+1. [quote](./modules/quote.md) - essential symbol info.
+1. [quoteSummary](./modules/quoteSummary.md) - comprehensive symbol info.
+1. [search](./modules/search.md) - symbol lookup, news and articles.
+1. [recommendationsBySymbol](./modules/recommendationsBySymbol.md) - similar symbols.
 
-<a name="error-handling"></name>
-## Error Handling and Validation.
+<a name="error-handling"></a>
+## Error Handling
 
-Coming soon.
+The modules rely on external services and *things can go wrong*.  Therefore,
+it's important to wrap your use of this library in try..catch statements,
+e.g.:
+
+```js
+let result;
+try {
+  result = await yahooFinance.quote(symbol);
+} catch (error) {
+  // Inspect error and decide what to do; often, you may want to just abort:
+  return;
+}
+
+doSomethingWith(result); // safe to use in the way you expect
+```
+
+So what can go wrong?
+
+* Network errors: request timeouts, no response, etc.
+* HTTP errors: internal errors, etc.
+* Missing resources, e.g. asking for fund data for a stock.
+* Validation errors.
+
+The library goes to great lengths to ensure that if there are no errors,
+the result you receive will be in an expected format and structure, that
+is safe to use, put in your database, perform calculations with, etc
+(but please do let us know if you come across any edge cases).
+
+There is a list of specific errors at [lib/errors.ts](../src/lib/errors.ts)
+but generally we'll prevent you from making bad requests with invalid option,
+etc.
 
 See also: [Validation](./validation.md)
 
 ## Validation
 
-See the [Validation docs](./validation.md).
+As per the previous section, if you do receive a result (i.e. if no error is
+thrown), it should reliably be in the format you expect.  As such, every
+received result is validated against the schema we've developed for each
+module.
+
+See the [Validation docs](./validation.md) for more info, including how to
+continue past validation errors or skip validation entirely, as long as you
+understand the risks.