geocoder model has doc (#14)

Geocoder client model now has javadoc.

libjava/lib/src/main/java/com/mapbox/services/geocoding/v5/GeocodingCriteria.java

@@ -1,19 +1,50 @@
 package com.mapbox.services.geocoding.v5;
 
-/**
- * Created by antonio on 1/30/16.
- */
 public final class GeocodingCriteria {
 
+    /**
+     * Default geocoding mode
+     */
     public static final String DATASET_PLACES = "mapbox.places";
+
+    /**
+     * Geocoding mode for for enterprise/batch geocoding
+     */
     public static final String DATASET_PLACES_PERMANENT = "mapbox.places-permanent";
 
+    /**
+     * Filter results by country
+     */
     public static final String TYPE_COUNTRY = "country";
+
+    /**
+     * Filter results by region
+     */
     public static final String TYPE_REGION = "region";
+
+    /**
+     * Filter results by postcode
+     */
     public static final String TYPE_POSTCODE = "postcode";
+
+    /**
+     * Filter results by place
+     */
     public static final String TYPE_PLACE = "place";
+
+    /**
+     * Filter results by neighborhood
+     */
     public static final String TYPE_NEIGHBORHOOD = "neighborhood";
+
+    /**
+     * Filter results by address
+     */
     public static final String TYPE_ADDRESS = "address";
+
+    /**
+     * Filter results by POI
+     */
     public static final String TYPE_POI = "poi";
 
 }

libjava/lib/src/main/java/com/mapbox/services/geocoding/v5/GeocodingService.java

@@ -9,10 +9,20 @@
 import rx.Observable;
 
 /**
- * Created by antonio on 1/30/16.
+ * Interface that defines the geocoding service.
  */
 public interface GeocodingService {
 
+    /**
+     * Call-based interface
+     *
+     * @param dataset
+     * @param query
+     * @param accessToken
+     * @param proximity
+     * @param types
+     * @return A retrofit Call object
+     */
     @GET("/geocoding/v5/{dataset}/{query}.json")
     Call<GeocodingResponse> getCall(
             @Path("dataset") String dataset,
@@ -21,6 +31,16 @@ Call<GeocodingResponse> getCall(
             @Query("proximity") String proximity,
             @Query("types") String types);
 
+    /**
+     * RxJava-based interface
+     *
+     * @param dataset
+     * @param query
+     * @param accessToken
+     * @param proximity
+     * @param types
+     * @return A RxJava Observable object
+     */
     @GET("/geocoding/v5/{dataset}/{query}.json")
     Observable<GeocodingResponse> getObservable(
             @Path("dataset") String dataset,

libjava/lib/src/main/java/com/mapbox/services/geocoding/v5/MapboxGeocoding.java

@@ -19,7 +19,7 @@
 import rx.Observable;
 
 /**
- * Created by antonio on 1/30/16.
+ * The Mapbox geocoding client (v5).
  */
 public class MapboxGeocoding implements MapboxService<GeocodingResponse> {
 
@@ -103,24 +103,17 @@ public Observable<GeocodingResponse> getObservable() {
         return observable;
     }
 
-    /*
-     * Builder
+    /**
+     * Builds your geocoder query by adding parameters.
      */
-
     public static class Builder extends MapboxBuilder {
 
-        /*
-         * Required
-         */
-
+        // Required
         private String accessToken;
         private String query;
         private String geocodingDataset;
 
-        /*
-         * Optional (Retrofit will omit these from the request if they remain null)
-         */
-
+        // Optional (Retrofit will omit these from the request if they remain null)
         private String proximity = null;
         private String geocodingType = null;
 
@@ -129,6 +122,12 @@ public Builder() {
             geocodingDataset = com.mapbox.services.geocoding.v5.GeocodingCriteria.DATASET_PLACES;
         }
 
+        /**
+         * Required to call when building {@link MapboxGeocoding.Builder}
+         *
+         * @param accessToken Mapbox access token, you must have a Mapbox account
+         *                    in order to use this library.
+         */
         @Override
         public Builder setAccessToken(String accessToken) {
             this.accessToken = accessToken;
@@ -151,22 +150,39 @@ public Builder setDataset(String geocodingDataset) {
             return this;
         }
 
+        /**
+         * Location around which to bias results.
+         *
+         * @param position A {@link Position}.
+         */
         public Builder setProximity(Position position) {
             if (position == null) return this;
             proximity = String.format("%f,%f", position.getLongitude(), position.getLatitude());
             return this;
         }
 
+        /**
+         * Filter results by one or more type. Options are country, region, postcode, place,
+         * locality, neighborhood, address, poi. Multiple options can be comma-separated.
+         *
+         * @param geocodingType String filtering the geocoder result types.
+         */
         public Builder setType(String geocodingType) {
             this.geocodingType = geocodingType;
             return this;
         }
 
+        /**
+         * @return your Mapbox access token.
+         */
         @Override
         public String getAccessToken() {
             return accessToken;
         }
 
+        /**
+         * @return your geocoder query.
+         */
         public String getQuery() {
             return query;
         }
@@ -175,10 +191,21 @@ public String getGeocodingDataset() {
             return geocodingDataset;
         }
 
+        /**
+         * Location around which you biased the results.
+         *
+         * @return String with the format longitude, latitude.
+         */
         public String getProximity() {
             return proximity;
         }
 
+        /**
+         * If you filtered your results by one or more types you can get what those filters are by
+         * using this method.
+         *
+         * @return String with list of filters you used.
+         */
         public String getGeocodingType() {
             return geocodingType;
         }
@@ -188,7 +215,5 @@ public MapboxGeocoding build() throws ServicesException {
             validateAccessToken(accessToken);
             return new MapboxGeocoding(this);
         }
-
     }
-
 }

libjava/lib/src/main/java/com/mapbox/services/geocoding/v5/models/FeatureContext.java

@@ -1,13 +1,24 @@
 package com.mapbox.services.geocoding.v5.models;
 
 /**
- * Created by antonio on 1/30/16.
+ * Feature context breaks down the places address and gives you more information about each part.
+ * In the case of an address it can give you the type id for each part and its name.
+ *
+ * @see <a href=https://mapbox.com/api-documentation/#geocoding>Geocoder Documentation</a>
  */
 public class FeatureContext {
 
     private String id;
     private String text;
 
+    /**
+     * Feature IDs are formatted like {type}.{id}. {type} is one of the following, "country",
+     * "region", "postcode", "place", "locality", "neighborhood", "address", or poi. Additional
+     * feature types may be added in the future, but the current types will stay the same. The
+     * numeric part of a feature ID may change between data updates.
+     *
+     * @return String with format {type}.{id}.
+     */
     public String getId() {
         return this.id;
     }
@@ -16,6 +27,11 @@ public void setId(String id) {
         this.id = id;
     }
 
+    /**
+     * Human-readable String describing a specific type.
+     *
+     * @return String with specific type name.
+     */
     public String getText() {
         return this.text;
     }

libjava/lib/src/main/java/com/mapbox/services/geocoding/v5/models/FeatureGeometry.java

@@ -4,7 +4,7 @@
 import java.util.List;
 
 /**
- * Created by antonio on 1/30/16.
+ * Describes the features geometry, useful for placing it on your map view.
  */
 public class FeatureGeometry {
 
@@ -15,6 +15,11 @@ public FeatureGeometry() {
         this.coordinates = new ArrayList<>();
     }
 
+    /**
+     * Gives the GeoJSON geometry type. Typically will be a "point".
+     *
+     * @return String with GeoJSON geometry type.
+     */
     public String getType() {
         return this.type;
     }
@@ -23,6 +28,11 @@ public void setType(String type) {
         this.type = type;
     }
 
+    /**
+     * List of feature coordinates that can be used to mark/draw the result on your map view.
+     *
+     * @return List containing longitude, latitude pair.
+     */
     public List<Double> getCoordinates() {
         return this.coordinates;
     }