Add documentation for the connection pool API

Update some weird argument names and field names so they make more sense.