Faraday Docs

[technoweenie]

Let's clean up the docs for Faraday v1. I'd like to settle on YARD for our documentation format. Ideally every public method and class has documentation with return values and parameter info. The more common or complex methods can have longer descriptions and even example code. Ideally, the docs are usable for source code spelunkers, while potentially generating snazzy web pages too (/cc #949).

• Satisfy Style/Documentation and Style/DocumentationMethods rubocop offenses RuboCop Quest Issue #854
• Document all public classes and methods using YARD
• Add YARD linter to CI CI: yard junk #958
• expanded, enhanced user guide in README and ./docs
• Specific doc requests
  • Adapter spec helper (extract to gem like faraday-adapter-specs)
  • adapter examples (multipart, retry, etc)
  • http proxy example

/cc older discussions #425 #575 #779

[technoweenie]

Closing this, #949 has this covered.