Document error handling

[dgr]

Problem/Opportunity
Today, most Etaoin API functions document what happens upon success, but they are largely silent about their behavior in error conditions. Do they return nil, another special value, or throw an exception? If they throw an exception, which ones? How do they distinguish between HTTP or TCP/IP exceptions that might happen while interacting with the WebDriver versus WebDriver errors? Are the behaviors for the various supported browsers consistent (is the same response returned or exception thrown for the same condition) or inconsistent?

Proposed Solution
Document the current behavior for error conditions. Where possible, understand differences between different WebDriver implementations.

Action
I can take a first level run at documenting the current behavior. This will probably generate a stream of PRs for doc string and User Guide updates.

[lread]

I think most fns that interact with the WebDriver throw on non-200 responses?
We probably don't want to get too specific about what type of exceptions can be thrown if the source is the WebDriver implementation.

I'm not terribly interested in documenting differences between WebDriver implementations, other than tips in the user guide under troubleshooting. Behaviors of WebDriver implementations are a moving target, and keeping this info fresh could become a full-time job.

[dgr]

I think this can be done in a fairly general way that won’t become a maintenance burden. Not every detail needs to be specified but the rough contours should be. And individual functions should specify whether exceptions are thrown for error conditions as opposed to returning error codes or nil.

[lread]

Ok, if you are willing, @dgr! Maybe start with a representative small example of fns in a PR (with supporting user guide docs if applicable). That way, we could review the general approach together before you get too far down the road.

[dgr]

Yep, sounds good.