[Not Ready] started work on geojson docs (#20)

Author: Cameron Mace

libjava/lib/src/main/java/com/mapbox/services/commons/geojson/Feature.java

@@ -8,7 +8,9 @@
 import com.mapbox.services.commons.models.Position;
 
 /**
- * Created by antonio on 1/30/16.
+ * A GeoJSON object with the type "Feature" is a feature object.
+ *
+ * @see <a href='geojson.org/geojson-spec.html#feature-objects'>Official GeoJSON Feature Specifications</a>
  */
 public class Feature implements GeoJSON {
 
@@ -17,69 +19,108 @@ public class Feature implements GeoJSON {
     private final JsonObject properties;
     private final String id;
 
-    /*
-     * Private constructor
+    /**
+     * Private constructor.
+     *
+     * @param geometry   {@link Geometry} object.
+     * @param properties of this feature as JSON.
+     * @param id         common identifier of this feature.
      */
-
     private Feature(Geometry geometry, JsonObject properties, String id) {
         this.geometry = geometry;
         this.properties = properties;
         this.id = id;
     }
 
-    /*
-     * Getters
+    /**
+     * Should always be "Feature".
+     *
+     * @return String "Feature".
      */
-
     @Override
     public String getType() {
         return type;
     }
 
+    /**
+     * Get the features {@link Geometry}.
+     *
+     * @return {@link Geometry} of the feature or null if not set.
+     */
     public Geometry getGeometry() {
         return geometry;
     }
 
+    /**
+     * Returns the optional properties of this feature as JSON.
+     *
+     * @return the properties of this feature
+     */
     public JsonObject getProperties() {
         return properties;
     }
 
+    /**
+     * The optional, common identifier of this feature.
+     *
+     * @return The common identifier of this feature, if set.
+     */
     public String getId() {
         return id;
     }
 
-    /*
-     * Factories
+    /**
+     * Create a feature from geometry.
+     *
+     * @param geometry {@link Geometry} object.
      */
-
     public static Feature fromGeometry(Geometry geometry) {
         return new Feature(geometry, null, null);
     }
 
+    /**
+     * Create a feature from geometry.
+     *
+     * @param geometry   {@link Geometry} object.
+     * @param properties of this feature as JSON.
+     */
     public static Feature fromGeometry(Geometry geometry, JsonObject properties) {
         return new Feature(geometry, properties, null);
     }
 
+    /**
+     * Create a feature from geometry.
+     *
+     * @param geometry   {@link Geometry} object.
+     * @param properties of this feature as JSON.
+     * @param id         common identifier of this feature.
+     */
     public static Feature fromGeometry(Geometry geometry, JsonObject properties, String id) {
         return new Feature(geometry, properties, id);
     }
 
-    /*
-     * Gson interface
+    /**
+     * Create a GeoJSON feature object from JSON.
+     *
+     * @param json String of JSON making up a feature.
+     * @return {@link Feature} GeoJSON object.
      */
-
     public static Feature fromJson(String json) {
         GsonBuilder gson = new GsonBuilder();
         gson.registerTypeAdapter(Position.class, new PositionDeserializer());
         gson.registerTypeAdapter(Geometry.class, new GeometryDeserializer());
         return gson.create().fromJson(json, Feature.class);
     }
 
+    /**
+     * Convert feature into JSON.
+     *
+     * @return String containing feature JSON.
+     */
     @Override
     public String toJson() {
         GsonBuilder gson = new GsonBuilder();
         gson.registerTypeAdapter(Position.class, new PositionSerializer());
         return gson.create().toJson(this);
     }
-
 }

libjava/lib/src/main/java/com/mapbox/services/commons/geojson/FeatureCollection.java

@@ -9,58 +9,76 @@
 import java.util.List;
 
 /**
- * Created by antonio on 1/30/16.
+ * A GeoJSON object with the type "FeatureCollection" is a feature object which represents a
+ * collection of feature objects.
+ *
+ * @see <a href='geojson.org/geojson-spec.html#feature-collection-objects'>Official GeoJSON FeatureCollection Specifications</a>
  */
 public class FeatureCollection implements GeoJSON {
 
     private final String type = "FeatureCollection";
     private final List<com.mapbox.services.commons.geojson.Feature> features;
 
-    /*
-     * Private constructor
+    /**
+     * Private constructor.
+     *
+     * @param features List of {@link Feature}.
      */
-
     private FeatureCollection(List<com.mapbox.services.commons.geojson.Feature> features) {
         this.features = features;
     }
 
-    /*
-     * Getters
+    /**
+     * Should always be "FeatureCollection".
+     *
+     * @return String "FeatureCollection".
      */
-
     @Override
     public String getType() {
         return type;
     }
 
+    /**
+     * Get the List containing all the features within collection.
+     *
+     * @return List of features within collection.
+     */
     public List<com.mapbox.services.commons.geojson.Feature> getFeatures() {
         return features;
     }
 
-    /*
-     * Factories
+    /**
+     * Create a {@link FeatureCollection} from a List of features.
+     *
+     * @param features List of {@link Feature}
+     * @return new {@link FeatureCollection}
      */
-
     public static FeatureCollection fromFeatures(List<com.mapbox.services.commons.geojson.Feature> features) {
         return new FeatureCollection(features);
     }
 
-        /*
-     * Gson interface
+    /**
+     * Create a GeoJSON feature collection object from JSON.
+     *
+     * @param json String of JSON making up a feature collection.
+     * @return {@link FeatureCollection} GeoJSON object.
      */
-
     public static FeatureCollection fromJson(String json) {
         GsonBuilder gson = new GsonBuilder();
         gson.registerTypeAdapter(Position.class, new PositionDeserializer());
         gson.registerTypeAdapter(Geometry.class, new GeometryDeserializer());
         return gson.create().fromJson(json, FeatureCollection.class);
     }
 
+    /**
+     * Convert feature collection into JSON.
+     *
+     * @return String containing feature collection JSON.
+     */
     @Override
     public String toJson() {
         GsonBuilder gson = new GsonBuilder();
         gson.registerTypeAdapter(Position.class, new PositionSerializer());
         return gson.create().toJson(this);
     }
-
 }

libjava/lib/src/main/java/com/mapbox/services/commons/geojson/GeoJSON.java

@@ -1,7 +1,7 @@
 package com.mapbox.services.commons.geojson;
 
 /**
- * Created by antonio on 1/30/16.
+ * Interface implemented by all GeoJSON objects, contains common fields.
  */
 public interface GeoJSON {
 

libjava/lib/src/main/java/com/mapbox/services/commons/geojson/Geometry.java

@@ -1,7 +1,8 @@
 package com.mapbox.services.commons.geojson;
 
 /**
- * Created by antonio on 1/30/16.
+ * Interface implemented by all Geometry objects, contains common fields.
+ * @param <T> the type of the coordinates, normally a list interface of positions.
  */
 public interface Geometry<T> extends com.mapbox.services.commons.geojson.GeoJSON {
 

libjava/lib/src/main/java/com/mapbox/services/commons/geojson/GeometryCollection.java

@@ -9,58 +9,76 @@
 import java.util.List;
 
 /**
- * Created by antonio on 1/30/16.
+ * A GeoJSON object with the type "GeometryCollection" is a geometry object which represents a
+ * collection of geometry objects.
+ *
+ * @see <a href='geojson.org/geojson-spec.html#geometry-collection'>Official GeoJSON GeometryCollection Specifications</a>
  */
-public class GeometryCollection implements com.mapbox.services.commons.geojson.GeoJSON {
+public class GeometryCollection implements GeoJSON {
 
     private final String type = "GeometryCollection";
     private final List<com.mapbox.services.commons.geojson.Geometry> geometries;
 
-    /*
-     * Private constructor
+    /**
+     * Private constructor.
+     *
+     * @param geometries List of {@link Geometry}.
      */
-
     public GeometryCollection(List<com.mapbox.services.commons.geojson.Geometry> geometries) {
         this.geometries = geometries;
     }
 
-    /*
-     * Getters
+    /**
+     * Should always be "GeometryCollection".
+     *
+     * @return String "GeometryCollection".
      */
-
     @Override
     public String getType() {
         return type;
     }
 
+    /**
+     * Get the List containing all the geometries within collection.
+     *
+     * @return List of geometries within collection.
+     */
     public List<com.mapbox.services.commons.geojson.Geometry> getGeometries() {
         return geometries;
     }
 
-    /*
-     * Factories
+    /**
+     * Create a {@link GeometryCollection} from a List of geometries.
+     *
+     * @param geometries List of {@link Geometry}
+     * @return new {@link GeometryCollection}
      */
-
     public static GeometryCollection fromGeometries(List<com.mapbox.services.commons.geojson.Geometry> geometries) {
         return new GeometryCollection(geometries);
     }
 
-    /*
-     * Gson interface
+    /**
+     * Create a GeoJSON geometry collection object from JSON.
+     *
+     * @param json String of JSON making up a geometry collection.
+     * @return {@link GeometryCollection} GeoJSON object.
      */
-
     public static GeometryCollection fromJson(String json) {
         GsonBuilder gson = new GsonBuilder();
         gson.registerTypeAdapter(Position.class, new PositionDeserializer());
         gson.registerTypeAdapter(Geometry.class, new GeometryDeserializer());
         return gson.create().fromJson(json, GeometryCollection.class);
     }
 
+    /**
+     * Convert geometry collection into JSON.
+     *
+     * @return String containing geometry collection JSON.
+     */
     @Override
     public String toJson() {
         GsonBuilder gson = new GsonBuilder();
         gson.registerTypeAdapter(Position.class, new PositionSerializer());
         return gson.create().toJson(this);
     }
-
 }