Jakew/refactorings/2018 06 12

Update ProGuard rules

- Use module name as file name to prevent conflicts
- Ignore JSR 305 annotations
- Clarify optimization rule

The parsing of annotations which define the shape of a request and the mechnism of request creation is independent of the response converter and call adapter parsing in the return type. Moreover, the request creation part is common to things like web sockets and server-sent events which might be supported in the future where the return type handling is completely different.

Ship R8/ProGuard rules in the jar.

* Encapsulate ServiceMethod creation inside the type

This will allow subtypes to be returned in the future.

* Rename one-letter type parameters to be more descriptive

Fun fact: this type and its builder were using R and T to mean the opposite things. 🤦

* Make the ServiceMethod entirely responsible for invocation

This way a base class can be exposed to the reflection-y bits and subtypes for different styles of requests can be implemented as subtypes.

Lock down JAXB. Don't load remote entities.

XML is subject to XXE attacks.
https://www.owasp.org/index.php/XML_External_Entity_(XXE)_Prevention_Cheat_Sheet#JAXB_Unmarshaller

Makes sure observable assembly hooks are called

This allows things like error and trace tracking to work naturally.

Fixes #2716

Small tweaks with exceptions.

Document that JAXB doesn't work on Android

Add a test for not overwriting headers.

To break the test, use Headers.Builder.set instead of add in ServiceMethod.

Fix local converter name.

Don't ever pass fatal errors to the callback.

Replace 'compile' with 'implementation

* Add missing nullability annotations.

* Inline single-use utility methods.

* Remove redundant throws.

* Inline method only called once.

Use HTTPS links in documentation where possible.

Closes: https://github.com/square/retrofit/issues/2425

Update to OkHttp 3.10.0.