Devise an approach for testing and documenting Flock's API

[julianharty]

Context

The API, documentation, and tests have been developed inconsistently on an ad-hoc basis. We'd like them to be consistent, documented, and tested by automated tests so the project team can continue to develop and revise the codebase with increased confidence through trustworthy automated tests that exercise typical usage of the API by end users.

Note: automated tests are extremely unlikely to detect all breaking changes and all adverse behaviours/effects. This issue is intended to cover the basic foundations that will facilitate ongoing improvements to the APIs, their documentation, and the range and depth of automated tests and testing.