Document the Connection API

[clintoncwolfe]

Description

As more people are using the Train plugin API, the mystery around the Connection API is creating obstacles to contribution. Let's get a developer doc going, possibly in comments, or in markdown.

By Connection API, I mean BaseConnection, all of its methods, clear understanding of what you must override and what you don't need to, and what you need to add.

This will likely also reveal cruft we may remove.

Train and Platform Version

1.5.0

[clintoncwolfe]

Refs #352, #366 , #356