Tweak and reorder YARD documentation

[epistrephein]

Pull Request description

• Rename attr_reader conn to connection
• Fix token_time and last_request class being Float and not Integer
• Put examples after descriptions, to mirror how yard renders the blocks and improve readability
• Remove redundant 'return' and 'exception raised' in @return and @raise blocks
• Add extended descriptions to all attr_readers
• Put 'Accepted values' and 'Default' in their own line
• Link module constants and methods with YARD markup
• Add a note linking to Faraday documentation
• Reorder attr_readers

Pull Request checklist

Kind of change

• My code is a minor change (typos, configuration, anything not related to core functionality)
• My code is a bug fix (non-breaking change which fixes an issue)
• My code is a new feature (non-breaking change which adds functionality)
• My code introduces a breaking change (fix or feature that would break existing functionality)

Style and tests

• My code follows the code style of this project
• I have added tests to cover my changes
• All new and existing tests passed

Documentation

• My change requires a change to the documentation
• I have updated the documentation accordingly

Changelog

• I have included the CHANGELOG entry for the changes