Adds more documentation about http modules

modules/okhttp-client/README.md

@@ -56,7 +56,7 @@ public static class ProxyHandler implements RequestHandler {
   }
 }
 ```
-## Add metrics to outgoing http requests
+## Adding metrics to outgoing http requests
 
 In order to have metrics for the outgoing http requests, the HttpMetricModule should be used
  together with HttpClientModule. 
@@ -72,4 +72,6 @@ public static void main(String[] args) throws Exception {
               .withModule(HttpMetricModule.create())
               .build();
 }
-```
+```
+
+It's important that `HttpMetricModule` to be declared **AFTER** `HttpClientModule`, otherwise the decorator won't work as expected. This is a short-coming of the framework that we [plan](https://github.com/spotify/apollo/issues/362) to fix in the future.

modules/okhttp-client/src/main/java/com/spotify/apollo/http/client/HttpClientModule.java

@@ -7,9 +7,7 @@
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
- * 
  *      http://www.apache.org/licenses/LICENSE-2.0
- * 
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@@ -19,17 +17,29 @@
  */
 package com.spotify.apollo.http.client;
 
+import com.google.inject.multibindings.Multibinder;
 import com.spotify.apollo.environment.ClientDecorator;
+import com.spotify.apollo.environment.IncomingRequestAwareClient;
 import com.spotify.apollo.module.AbstractApolloModule;
 import com.spotify.apollo.module.ApolloModule;
-
-import com.google.inject.multibindings.Multibinder;
 import com.squareup.okhttp.OkHttpClient;
 
+/**
+ * Module extends {@link IncomingRequestAwareClient} to be able to handle HTTP calls.
+ *
+ * <p>You can also use the {@link OkHttpClient} in case you don't want to use the apollo client, but
+ * doing so won't provide you with metrics (which still needs to be enabled by using the {@link
+ * HttpMetricModule}).
+ *
+ * @see OkHttpClientProvider
+ * @see HttpMetricModule
+ * @see IncomingRequestAwareClient
+ * @see com.spotify.apollo.Client
+ * @see com.spotify.apollo.Environment#client()
+ */
 public class HttpClientModule extends AbstractApolloModule {
 
-  private HttpClientModule() {
-  }
+  private HttpClientModule() {}
 
   public static ApolloModule create() {
     return new HttpClientModule();
@@ -38,7 +48,8 @@ public static ApolloModule create() {
   @Override
   protected void configure() {
     Multibinder.newSetBinder(binder(), ClientDecorator.class)
-        .addBinding().to(HttpClientDecorator.class);
+        .addBinding()
+        .to(HttpClientDecorator.class);
 
     bind(HttpClient.class);
     bind(OkHttpClient.class).toProvider(OkHttpClientProvider.class);

modules/okhttp-client/src/main/java/com/spotify/apollo/http/client/HttpMetricModule.java

@@ -7,9 +7,7 @@
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
- * 
  *      http://www.apache.org/licenses/LICENSE-2.0
- * 
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@@ -28,6 +26,35 @@
 import com.spotify.apollo.module.ApolloModule;
 import com.spotify.metrics.core.SemanticMetricRegistry;
 
+/**
+ * Module that adds metrics to any http call using the Apollo client.
+ *
+ * <p>The declaration of this module must be done <b>AFTER</b> the {@link HttpClientModule} like so:
+ *
+ * <blockquote>
+ *
+ * See <a href="https://github.com/spotify/apollo/issues/362">issue#362</a> for more information *
+ * of why the order matters.
+ *
+ * </blockquote>
+ *
+ * <pre>
+ * Services.usingName(SERVICE_NAME)
+ *   // ...
+ *   .withModule(HttpClientModule.create())
+ *   .withModule(HttpMetricModule.create())
+ *   // ...
+ * </pre>
+ *
+ * <p>Any usage of {@link com.spotify.apollo.Client} should now send metrics to the registered
+ * metric registry.
+ *
+ * @see HttpClientModule
+ * @see com.spotify.apollo.Environment#client()
+ * @see IncomingRequestAwareClient
+ * @see com.spotify.apollo.Client
+ * @see MetricsHttpClient
+ */
 public class HttpMetricModule extends AbstractApolloModule {
 
   public static ApolloModule create() {

modules/okhttp-client/src/main/java/com/spotify/apollo/http/client/OkHttpClientProvider.java

@@ -7,9 +7,7 @@
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
- * 
  *      http://www.apache.org/licenses/LICENSE-2.0
- * 
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@@ -19,20 +17,18 @@
  */
 package com.spotify.apollo.http.client;
 
+import static com.spotify.apollo.environment.ConfigUtil.optionalBoolean;
+import static com.spotify.apollo.environment.ConfigUtil.optionalInt;
+
 import com.google.common.io.Closer;
 import com.google.inject.Inject;
 import com.google.inject.Provider;
-
 import com.squareup.okhttp.ConnectionPool;
 import com.squareup.okhttp.OkHttpClient;
 import com.typesafe.config.Config;
-
 import java.util.Optional;
 import java.util.concurrent.TimeUnit;
 
-import static com.spotify.apollo.environment.ConfigUtil.optionalBoolean;
-import static com.spotify.apollo.environment.ConfigUtil.optionalInt;
-
 class OkHttpClientProvider implements Provider<OkHttpClient> {
 
   private final OkHttpClientConfig config;