Merge pull request #6 from jasnell/20140417-generalimprovements

Mostly javadoc improvements. A few minor api tweaks as well.

geo/src/main/java/com/ibm/common/geojson/AS1Position.java

@@ -30,6 +30,11 @@ import com.ibm.common.activitystreams.ASObject;
 
 /**
  * Represents an Activity Streams 1.0 style position object
+ * see (https://github.com/activitystreams/activity-schema/blob/master/activity-schema.md)
+ * 
+ * Use of the AS1Position object is deprecated. Use the GeoJSON mechanisms
+ * instead
+ * 
  * @author james
  * @deprecated Use Position
  */
@@ -43,14 +48,29 @@ public final class AS1Position
       objectType("position");
     }
     
+    /**
+     * Set the latitude
+     * @param latitude float
+     * @return Builder
+     */
     public Builder latitude(float latitude) {
       return set("latitude", max(0f,min(90.0f,latitude)));
     }
     
+    /**
+     * Set the longitude
+     * @param longitude float
+     * @return Builder
+     */
     public Builder longitude(float longitude) {
       return set("longitude", max(-180.0f,min(180.0f,longitude)));
     }
     
+    /**
+     * Set the altitude
+     * @param altitude float
+     * @return Builder
+     */
     public Builder altitude(float altitude) {
       return set("altitude", altitude);
     }
@@ -66,18 +86,33 @@ public final class AS1Position
     super(builder);
   }
   
+  /**
+   * Get the latitude 
+   * @return float
+   */
   public float latitude() {
     return max(0f,min(90.0f,getFloat("latitude")));
   }
   
+  /**
+   * Get the longitude
+   * @return float
+   */
   public float longitude() {
     return max(-180.0f,min(180.0f,getFloat("longitude")));
   }
   
+  /**
+   * Get the altitude. If the altitude property is not set, this 
+   * will return Float.MIN_VALUE;
+   * @return float
+   */
   public float altitude() {
-    return getFloat("altitude");
+    return getFloat("altitude", Float.MIN_VALUE);
   }
   
+  // Java Serialization Support
+  
   Object writeReplace() throws java.io.ObjectStreamException {
     return new SerializedForm(this);
   }

geo/src/main/java/com/ibm/common/geojson/Address.java

@@ -25,6 +25,14 @@ import java.io.ObjectStreamException;
 
 import com.ibm.common.activitystreams.ASObject;
 
+/**
+ * A simple non-GeoJSON Address object modelled after the 
+ * legacy Activity Streams 1.0 Address object 
+ * (see https://github.com/activitystreams/activity-schema/blob/master/activity-schema.md)
+ * 
+ * @author james
+ *
+ */
 public final class Address 
   extends ASObject {
 
@@ -35,30 +43,65 @@ public final class Address
       objectType("address");
     }
     
+    /**
+     * The full mailing address formatted for display or use 
+     * with a printed mailing label.
+     * @param formatted String
+     * @return Builder
+     */
     public Builder formatted(String formatted) {
       return set("formatted", formatted);
     }
     
+    /**
+     * The street address including house number, street name, P.O. Box, 
+     * apartment or unit number and extended multi-line address information.
+     * @param streetAddress String
+     * @return Builder
+     */
     public Builder streetAddress(String streetAddress) {
       return set("streetAddress", streetAddress);
     }
     
+    /**
+     * The city or locality
+     * @param locality String
+     * @return Builder
+     */
     public Builder locality(String locality) {
       return set("locality", locality);
     }
     
+    /**
+     * The state or region
+     * @param region String
+     * @return Builder
+     */
     public Builder region(String region) {
       return set("region", region);
     }
     
+    /**
+     * The zip or postal code
+     * @param postalCode String
+     * @return Builder
+     */
     public Builder postalCode(String postalCode) {
       return set("postalCode", postalCode);
     }
     
+    /**
+     * The country name component
+     * @param country String
+     * @return Builder
+     */
     public Builder country(String country) {
       return set("country", country);
     }
     
+    /**
+     * Get the completed Address object
+     */
     @Override
     public Address get() {
       return new Address(this);
@@ -70,30 +113,58 @@ public final class Address
     super(builder);
   }
   
+  /**
+   * The full mailing address formatted for display or use 
+   * with a printed mailing label.
+   * @return String
+   */
   public String formatted() {
     return getString("formatted");
   }
   
+  /**
+   * The street address including house number, street name, P.O. Box, 
+   * apartment or unit number and extended multi-line address information.
+   * @return String
+   */
   public String streetAddress() {
     return getString("streetAddress");
   }
   
+  /**
+   * The city or locality
+   * @return String
+   */
   public String locality() {
     return getString("locality");
   }
   
+  /**
+   * The state or region
+   * @return String
+   */
   public String region() {
     return getString("region");
   }
   
+  /**
+   * The zip or postal code
+   * @return String
+   */
   public String postalCode() {
     return getString("postalCode");
   }
   
+  /**
+   * The country name component
+   * @return String
+   */
   public String country() {
     return getString("country");
   }
   
+  // Java Serialization Support
+  
   Object writeReplace() throws java.io.ObjectStreamException {
     return new SerializedForm(this);
   }

geo/src/main/java/com/ibm/common/geojson/BoundingBox.java

@@ -31,6 +31,10 @@ import com.google.common.collect.ImmutableList;
 import com.google.common.collect.ImmutableSortedSet;
 import com.google.common.collect.Iterables;
 
+/**
+ * A GeoJSON Bounding Box (see http://geojson.org/geojson-spec.html#bounding-boxes)
+ * @author james
+ */
 public final class BoundingBox
   implements Iterable<Float>, Serializable {
 
@@ -114,6 +118,11 @@ public final class BoundingBox
       zset.build());
   }
   
+  /**
+   * Calculate the Bounding Box for a collection of Polygon objects
+   * @param polygons Iterable&ltPolygon>
+   * @return BoundingBox
+   */
   public static BoundingBox calculateBoundingBoxPolygons(Iterable<Polygon> polygons) {
     ImmutableSortedSet.Builder<Float> xset = 
       ImmutableSortedSet.naturalOrder();

geo/src/main/java/com/ibm/common/geojson/CRS.java

@@ -30,6 +30,11 @@ import com.google.common.base.Objects;
 import com.google.common.base.Supplier;
 import com.google.common.collect.ImmutableMap;
 
+/**
+ * A GeoJSON Coordinate Reference System description
+ * see http://geojson.org/geojson-spec.html#coordinate-reference-system-objects
+ * @author james
+ */
 public final class CRS
   implements Iterable<String>, Serializable {
 

geo/src/main/java/com/ibm/common/geojson/Feature.java

@@ -30,6 +30,11 @@ import java.util.Map;
 import com.google.common.base.Supplier;
 import com.google.common.collect.ImmutableMap;
 
+/**
+ * A GeoJSON Feature Object
+ * see http://geojson.org/geojson-spec.html#feature-objects
+ * @author james
+ */
 public final class Feature 
   extends GeoObject<Feature>
   implements Iterable<String> {

geo/src/main/java/com/ibm/common/geojson/FeatureCollection.java

@@ -30,6 +30,12 @@ import com.google.common.base.Supplier;
 import com.google.common.collect.ImmutableList;
 import com.google.common.collect.Iterables;
 
+/**
+ * A GeoJSON FeatureCollection object
+ * see http://geojson.org/geojson-spec.html#feature-collection-objects
+ * @author james
+ *
+ */
 public final class FeatureCollection 
   extends GeoObject<FeatureCollection>
   implements Iterable<Feature> {

geo/src/main/java/com/ibm/common/geojson/GeoMakers.java

@@ -21,6 +21,11 @@
  */
 package com.ibm.common.geojson;
 
+/**
+ * Makers for the various GeoJSON object types
+ * @author james
+ *
+ */
 @SuppressWarnings("deprecation")
 public final class GeoMakers {
 

geo/src/main/java/com/ibm/common/geojson/GeoObject.java

@@ -30,6 +30,13 @@ import com.google.common.base.Supplier;
 import static com.google.common.collect.ImmutableMap.copyOf;
 import static com.google.common.collect.Maps.newLinkedHashMap;
 
+/**
+ * The base class for all GeoJSON objects. The type of object is identified
+ * by the type() property. 
+ * @author james
+ *
+ * @param <G>
+ */
 @SuppressWarnings("unchecked")
 public abstract class GeoObject<G extends GeoObject<G>>
   implements Serializable {
@@ -57,29 +64,60 @@ public abstract class GeoObject<G extends GeoObject<G>>
     protected Map<String,Object> data = 
       newLinkedHashMap();
     
+    /**
+     * Auto-calculate the bounding box when the object is created
+     * @return Builder
+     */
     public B calculateBoundingBox() {
       this.withBoundingBox = true;
       return (B)this;
     }
     
+    /**
+     * Use the given object as a template when creating this one
+     * @param geo GeObject&lt;?>
+     * @return Builder
+     */
     protected B from(GeoObject<?> geo) {
       data.putAll(geo.data);
       return (B)this;
     }
     
+    /**
+     * Set the object type
+     * @param type Type
+     * @return Builder
+     */
     public B type(Type type) {
       this.type = type;
       return (B)this;
     }
     
+    /**
+     * Set the CRS
+     * @param crs CRS
+     * @return Builder
+     */
     public B crs(CRS crs) {
       return set("crs", crs);
     }
     
+    /**
+     * Set the bounding box explicitly
+     * @param bbox BoundingBox
+     * @return Builder
+     * @see GeoObject.Builder.calculateBoundingBox()
+     */
     public B boundingBox(BoundingBox bbox) {
       return set("bbox", bbox);
     }
     
+    /**
+     * Set an additional property on this object
+     * @param name String
+     * @param val Object
+     * @return Builder
+     */
     public B set(String name, Object val) {
       if (val != null)
         this.data.put(name,val);
@@ -88,6 +126,9 @@ public abstract class GeoObject<G extends GeoObject<G>>
       return (B)this;
     }
     
+    /**
+     * Get the built object
+     */
     public final G get() {
       preGet();
       G g =  doGet();
@@ -107,6 +148,10 @@ public abstract class GeoObject<G extends GeoObject<G>>
     this.data = copyOf(builder.data);
   }
   
+  /**
+   * Return the type of object
+   * @return Type
+   */
   public Type type() {
     return type;
   }
@@ -124,14 +169,26 @@ public abstract class GeoObject<G extends GeoObject<G>>
     return data.containsKey(name);
   }
   
+  /**
+   * Return the CRS for this object
+   * @return CRS
+   */
   public CRS crs() {
     return this.<CRS>get("crs", null);
   }
   
+  /**
+   * Return the bounding box for this object
+   * @return BoundingBox
+   */
   public BoundingBox boundingBox() {
     return this.<BoundingBox>get("bbox", null);
   }
 
+  /**
+   * Return a copy of this object with a calculated bounding box
+   * @return G (a copy of this object)
+   */
   public final G withBoundingBox() {
     return has("bbox") ? 
       (G)this : makeWithBoundingBox();

geo/src/main/java/com/ibm/common/geojson/GeometryCollection.java

@@ -29,6 +29,12 @@ import java.util.Iterator;
 import com.google.common.collect.ImmutableList;
 import com.google.common.collect.Iterables;
 
+/**
+ * A GeoJSON GeometryCollection object
+ * see http://geojson.org/geojson-spec.html#geometry-collection
+ * @author james
+ *
+ */
 public final class GeometryCollection 
   extends Geometry<GeometryCollection, Geometry<?,?>> {
 

geo/src/main/java/com/ibm/common/geojson/LineString.java

@@ -35,6 +35,34 @@ import com.google.common.base.Supplier;
 import com.google.common.collect.ImmutableList;
 import com.ibm.common.geojson.Geometry.CoordinateGeometry;
 
+/**
+ * A GeoJSON LineString object
+ * See http://geojson.org/geojson-spec.html#linestring.
+ * 
+ * The LineString can optionally be a Linear Ring if there are at least four
+ * positions and the first and last position are equivalent.
+ * 
+ * <pre>
+ *   LineString regularLineString = 
+ *     GeoMakers.linestring()
+ *       .add(1,2)
+ *       .add(2,3)
+ *       .get();
+ *   // includes points (1,2) and (2,3)
+ *       
+ *   LineString linearRing = 
+ *     GeoMakers.linestring()
+ *       .linearRing()
+ *       .add(1,2)
+ *       .add(2,3)
+ *       .add(3,4)
+ *       .get()
+ *   // includes points (1,2), (2,3), (3,4) and (1,2)
+ * </pre>
+ * 
+ * @author james
+ *
+ */
 public final class LineString 
   extends CoordinateGeometry<LineString,Position,Iterable<Position>> {
 
@@ -56,6 +84,10 @@ public final class LineString
       type(Type.LINESTRING);
     }
     
+    /**
+     * Specify that this LineString is a linearring
+     * @return Builder
+     */
     public Builder linearRing() {
       return linearRing(true);
     }
@@ -65,6 +97,12 @@ public final class LineString
       return this;
     }
     
+    /**
+     * Add one or more positions to this linestring
+     * @param position Position
+     * @param positions Position[] optional vararg 
+     * @return Builder
+     */
     public Builder add(Position position, Position... positions) {
       this.positions.add(position);
       if (positions != null) 
@@ -73,19 +111,42 @@ public final class LineString
       return this;
     }
     
+    /**
+     * Add a single position to this linestring
+     * @param x float
+     * @param y float
+     * @return Builder
+     */
     public Builder add(float x, float y) {
       return add(GeoObject.position(x, y));
     }
     
+    /**
+     * Add a single position to this linestring
+     * @param position Supplier&lt;Position> 
+     * @return Builder
+     */
     public Builder add(Supplier<Position> position) {
       return add(position.get());
     }
     
+    /**
+     * Add one or more positions to this linestring
+     * @param positions Iterable&lt;Position>
+     * @return Builder
+     */
     public Builder add(Iterable<Position> positions) {
       this.positions.addAll(positions);
       return this;
     }
     
+    /**
+     * Add a single position to this linestring 
+     * @param x float
+     * @param y float
+     * @param z float
+     * @return Builder
+     */
     public Builder add(float x, float y, float z) {
       return add(GeoObject.position(x,y,z));
     }
@@ -122,6 +183,10 @@ public final class LineString
   }
 
   @Override
+  /**
+   * Get this LineStrings positions
+   * @return Iterable&lt;Position>
+   */
   public Iterable<Position> coordinates() {
     Iterable<Position> pos = super.coordinates();
     if (!ring)
@@ -138,6 +203,9 @@ public final class LineString
     return coordinates().iterator();
   }
   
+  /**
+   * Return a copy of this linestring with a calculated bounding box
+   */
   @Override
   public LineString makeWithBoundingBox() {
     return new LineString.Builder()
@@ -146,6 +214,8 @@ public final class LineString
       .boundingBox(calculateBoundingBoxPositions(this))
       .get();
   }
+  
+  // Java Serialization support
 
   Object writeReplace() throws java.io.ObjectStreamException {
     return new SerializedForm(this);

geo/src/main/java/com/ibm/common/geojson/MultiLineString.java

@@ -30,6 +30,12 @@ import com.google.common.base.Supplier;
 import com.google.common.collect.ImmutableList;
 import com.ibm.common.geojson.Geometry.CoordinateGeometry;
 
+/**
+ * A GeoJSON MultiLineString object
+ * see http://geojson.org/geojson-spec.html#multilinestring
+ * @author james
+ *
+ */
 public final class MultiLineString 
   extends CoordinateGeometry<MultiLineString,LineString,Iterable<LineString>> {
 
@@ -43,6 +49,12 @@ public final class MultiLineString
       type(Type.MULTILINESTRING);
     }
     
+    /**
+     * Add one or more LineStrings
+     * @param line LineString
+     * @param lines LineString[] optional vararg
+     * @return Builder
+     */
     public Builder add(LineString line, LineString... lines) {
       this.strings.add(line);
       if (lines != null)
@@ -51,10 +63,20 @@ public final class MultiLineString
       return this;
     }
     
+    /**
+     * Add a single LineString
+     * @param line Supplier&lt;LineString>
+     * @return Builder
+     */
     public Builder add(Supplier<LineString> line) {
       return add(line.get());
     }
     
+    /**
+     * Add one or more LineStrings
+     * @param lines Iterable&lt;LineString>
+     * @return Builder
+     */
     public Builder add(Iterable<LineString> lines) {
       this.strings.addAll(lines);
       return this;
@@ -64,6 +86,10 @@ public final class MultiLineString
       return new MultiLineString(this);
     }
 
+    /**
+     * Get this objects collection of LineStrings
+     * @return Iterable&lt;LineString>
+     */
     @Override
     protected Iterable<LineString> coordinates() {
       return strings.build();
@@ -81,6 +107,10 @@ public final class MultiLineString
     return coordinates().iterator();
   }
 
+  /** 
+   * Copy this object with a calculated bounding box
+   * @return MultiLineString
+   */
   @Override
   protected MultiLineString makeWithBoundingBox() {
     return new MultiLineString.Builder()

geo/src/main/java/com/ibm/common/geojson/MultiPoint.java

@@ -30,6 +30,12 @@ import com.ibm.common.geojson.Geometry.CoordinateGeometry;
 
 import static com.ibm.common.geojson.BoundingBox.calculateBoundingBoxPositions;
 
+/**
+ * A GeoJSON MultiPoint object
+ * see http://geojson.org/geojson-spec.html#multipoint
+ * @author james
+ *
+ */
 public final class MultiPoint 
   extends CoordinateGeometry<MultiPoint,Position,Iterable<Position>> {
 
@@ -43,6 +49,12 @@ public final class MultiPoint
       type(GeoObject.Type.MULTIPOINT);
     }
     
+    /**
+     * Add one or more positions
+     * @param position Position
+     * @param positions Position[] optional vararg
+     * @return Builder
+     */
     public Builder add(Position position, Position... positions) {
       list.add(position);
       if (positions != null)
@@ -50,19 +62,42 @@ public final class MultiPoint
       return this;
     }
     
+    /**
+     * Add one or more positions 
+     * @param positions Iterable&lt;Position>
+     * @return Builder
+     */
     public Builder add(Iterable<Position> positions) {
       list.addAll(positions);
       return this;
     }
     
+    /**
+     * Add a position
+     * @param pos Supplier&lt;Position>
+     * @return Builder
+     */
     public Builder add(Supplier<Position> pos) {
       return add(pos.get());
     }
     
+    /**
+     * Add a position
+     * @param x float
+     * @param y float 
+     * @return Builder
+     */
     public Builder add(float x, float y) {
       return add(GeoObject.position(x, y));
     }
     
+    /**
+     * Add a position
+     * @param x float
+     * @param y float
+     * @param z float
+     * @return Builder
+     */
     public Builder add(float x, float y, float z) {
       return add(GeoObject.position(x,y,z));
     }
@@ -89,6 +124,10 @@ public final class MultiPoint
     return coordinates().iterator();
   }
 
+  /**
+   * Return a copy of this object with a calculated bounding box
+   * @return MultiPoint
+   */
   @Override
   protected MultiPoint makeWithBoundingBox() {
     return new MultiPoint.Builder()

geo/src/main/java/com/ibm/common/geojson/MultiPolygon.java

@@ -30,6 +30,12 @@ import com.google.common.base.Supplier;
 import com.google.common.collect.ImmutableList;
 import com.ibm.common.geojson.Geometry.CoordinateGeometry;
 
+/**
+ * A GeoJSON MultiPolygon object.
+ * see http://geojson.org/geojson-spec.html#multipolygon
+ * @author james
+ *
+ */
 public final class MultiPolygon 
   extends CoordinateGeometry<MultiPolygon, Polygon, Iterable<Polygon>>{
 
@@ -43,6 +49,12 @@ public final class MultiPolygon
       type(Type.MULTIPOLYGON);
     }
     
+    /**
+     * Add one or more Polygons
+     * @param poly Polygon
+     * @param polys Polygon[] optional vararg
+     * @return Builder
+     */
     public Builder add(Polygon poly, Polygon... polys) {
       // TODO: Check hole requirement
       this.strings.add(poly);
@@ -52,10 +64,20 @@ public final class MultiPolygon
       return this;
     }
     
+    /**
+     * Add a Polygon
+     * @param poly Supplier&lt;Polygon>
+     * @return Builder
+     */
     public Builder add(Supplier<Polygon> poly) {
       return add(poly.get());
     }
     
+    /**
+     * Add one ore more Polygons
+     * @param polygons Iterable&lt;Polygon>
+     * @return Builder
+     */
     public Builder add(Iterable<Polygon> polygons) {
       this.strings.addAll(polygons);
       return this;
@@ -82,6 +104,10 @@ public final class MultiPolygon
     return coordinates().iterator();
   }
 
+  /**
+   * Return a copy of this object with a calculated bounding box
+   * @return MultiPolygon
+   */
   @Override
   protected MultiPolygon makeWithBoundingBox() {
     return new MultiPolygon.Builder()

geo/src/main/java/com/ibm/common/geojson/Place.java

@@ -26,6 +26,15 @@ import java.io.ObjectStreamException;
 import com.google.common.base.Supplier;
 import com.ibm.common.activitystreams.ASObject;
 
+/**
+ * A legacy Activity Streams 1.0 Place object
+ * see https://github.com/activitystreams/activity-schema/blob/master/activity-schema.md.
+ * 
+ * Place objects have additional address, position and geo properties that
+ * describe the location.
+ * @author james
+ *
+ */
 public final class Place extends ASObject {
 
   public static final class Builder 
@@ -35,25 +44,52 @@ public final class Place extends ASObject {
       objectType("place");
     }
     
+    /**
+     * Set the address
+     * @param address Address
+     * @return Builder
+     */
     public Builder address(Address address) {
       return set("address", address);
     }
     
+    /**
+     * Set the address
+     * @param address Supplier<Address>
+     * @return Builder
+     */
     public Builder address(Supplier<Address> address) {
       return address(address.get());
     }
     
-    @SuppressWarnings("deprecation") 
+    /**
+     * Set the position 
+     * @deprecated
+     * @param position AS1Position
+     * @return Builder
+     */
     public Builder position(AS1Position position) {
       return set("position", position);
     }
     
-    @SuppressWarnings("deprecation")
+    /**
+     * Set the position
+     * @deprecated 
+     * @param position Supplier&lt;AS1Position>
+     * @return Builder
+     */
     public Builder position(Supplier<AS1Position> position) {
       return position(position.get());
     }
     
-    @SuppressWarnings("deprecation")
+    /**
+     * Set the position
+     * @param latitude float
+     * @param longitude float
+     * @param altitude float
+     * @return Builder
+     * @deprecated
+     */
     public Builder position(
       float latitude, 
       float longitude, 
@@ -61,10 +97,20 @@ public final class Place extends ASObject {
       return position(GeoMakers.as1Position(latitude, longitude, altitude));
     }
     
+    /**
+     * Set the geo property
+     * @param geo GeoObject&lt;?> Any GeoJSON object can be used
+     * @return Builder
+     */ 
     public Builder geo(GeoObject<?> geo) {
       return set("geo", geo);
     }
     
+    /**
+     * Set the geo property
+     * @param geo Supplier&lt;? extends GeoObject&lt;?>> Any GeoJSON object can be used
+     * @return Builder
+     */ 
     public Builder geo(Supplier<? extends GeoObject<?>> geo) {
       return geo(geo.get());
     }
@@ -80,15 +126,27 @@ public final class Place extends ASObject {
     super(builder);
   }
   
+  /**
+   * Get the address
+   * @return Address
+   */
   public Address address() {
     return this.<Address>get("address");
   }
   
-  @SuppressWarnings("deprecation")
+  /**
+   * Get the position
+   * @deprecated
+   * @return AS1Position
+   */
   public AS1Position position() {
     return this.<AS1Position>get("position");
   }
   
+  /**
+   * Get the geo property
+   * @return &lt;G extends GeoObject&lt;?>>G
+   */
   public <G extends GeoObject<?>>G geo() {
     return this.<G>get("geo");
   }

geo/src/main/java/com/ibm/common/geojson/Point.java

@@ -31,6 +31,15 @@ import static com.ibm.common.geojson.BoundingBox.calculateBoundingBox;
 
 import com.ibm.common.geojson.Geometry.CoordinateGeometry;
 
+/**
+ * A GeoJSON Point object
+ * see http://geojson.org/geojson-spec.html#point.
+ * 
+ * A Point object represents a single Position
+ * 
+ * @author james
+ *
+ */
 public final class Point 
   extends CoordinateGeometry<Point,Position,Position> {
 
@@ -43,21 +52,44 @@ public final class Point
       type(GeoObject.Type.POINT);
     }
     
-    public Builder position(float x, float y, float z) {
+    /**
-      this.position = GeoObject.position(x, y, z);
+     * Set the position
+     * @param northing float
+     * @param easting float
+     * @param altitude float
+     * @return Builder
+     */
+    public Builder position(float northing, float easting, float altitude) {
+      this.position = GeoObject.position(northing, easting, altitude);
       return this;
     }
     
-    public Builder position(float x, float y) {
+    /**
-      this.position = GeoObject.position(x,y);
+     * Set the position
+     * @param northing float
+     * @param easting float
+     * @return Builder
+     */
+    public Builder position(float northing, float easting) {
+      this.position = GeoObject.position(northing,easting);
       return this;
     }
     
+    /**
+     * Set the position
+     * @param position Position
+     * @return Builder
+     */
     public Builder position(Position position) {
       this.position = position;
       return this;
     }
     
+    /**
+     * Set the position 
+     * @param position Supplier&lt;Position> 
+     * @return Builder
+     */
     public Builder position(Supplier<Position> position) {
       return position(position.get());
     }

geo/src/main/java/com/ibm/common/geojson/Polygon.java

@@ -31,6 +31,12 @@ import com.google.common.base.Supplier;
 import com.google.common.collect.ImmutableList;
 import com.ibm.common.geojson.Geometry.CoordinateGeometry;
 
+/**
+ * A GeoJSON Polygon object
+ * see http://geojson.org/geojson-spec.html#polygon
+ * @author james
+ *
+ */
 public final class Polygon 
   extends CoordinateGeometry<Polygon,LineString, Iterable<LineString>>  {
 
@@ -44,6 +50,12 @@ public final class Polygon
       type(Type.POLYGON);
     }
     
+    /**
+     * Add one or more LineStrings
+     * @param line LineString
+     * @param lines LineString[] optional vararg
+     * @return Builder
+     */
     public Builder add(LineString line, LineString... lines) {
       checkArgument(line.linearRing(), "Polygon coordinates MUST be Linear Rings"); 
       // TODO: Check hole requirement
@@ -54,10 +66,20 @@ public final class Polygon
       return this;
     }
     
+    /**
+     * Add a LineString
+     * @param line Supplier&lt;LineString>
+     * @return Builder
+     */
     public Builder add(Supplier<LineString> line) {
       return add(line.get());
     }
     
+    /**
+     * Add one or more LineStrings
+     * @param lines Iterable&lt;LineString>
+     * @return Builder
+     */
     public Builder add(Iterable<LineString> lines) {
       this.strings.addAll(lines);
       return this;

geo/src/main/java/com/ibm/common/geojson/Position.java

@@ -33,6 +33,16 @@ import com.google.common.base.Supplier;
 import com.google.common.collect.ImmutableList;
 import com.google.common.primitives.Floats;
 
+/**
+ * A GeoJSON Position
+ * see http://geojson.org/geojson-spec.html#positions. 
+ * 
+ * Position objects consist primarily of three distinct values:
+ * a northing (latitude or x), easting (longitude or y) and altitude (z). 
+ * 
+ * @author james
+ *
+ */
 public final class Position 
   implements Iterable<Float>, Serializable  {
 

geo/src/main/java/com/ibm/common/geojson/as2/GeoModule.java

@@ -32,6 +32,21 @@ import com.ibm.common.geojson.Address;
 import com.ibm.common.geojson.GeoObject;
 import com.ibm.common.geojson.Place;
 
+/**
+ * Enables the use of the GeoJSON extensions with Activity Streams 2.0
+ * 
+ * <pre>
+ *   import com.ibm.common.geojson.as2.GeoModule;
+ *   import com.ibm.common.activitystreams.IO;
+ *   
+ *   //...
+ *   
+ *   IO io = IO.makeDefault(GeoModule.instance);
+ *   
+ * </pre>
+ * @author james
+ *
+ */
 @SuppressWarnings("deprecation")
 public final class GeoModule 
   implements Module {

legacy/src/main/java/com/ibm/common/activitystreams/legacy/AudioVisual.java

@@ -26,24 +26,50 @@ import java.io.ObjectStreamException;
 import com.google.common.base.Supplier;
 import com.ibm.common.activitystreams.ASObject;
 
+/**
+ * For the legacy "audio" and "video" objectTypes. These have 
+ * a String "embedCode" property whose value specifies a 
+ * snippet of HTML for embedding the resource and a stream
+ * MediaLink property.
+ * 
+ * @author james
+ */
 public final class AudioVisual 
   extends ASObject {
 
   public static final class Builder 
     extends ASObject.AbstractBuilder<AudioVisual,Builder> {
 
+    /**
+     * Set the embedCode
+     * @param embed String
+     * @return Builder
+     */
     public Builder embedCode(String embed) {
       return set("embedCode", embed);
     }
     
+    /**
+     * Set the stream MediaLink
+     * @param mediaLink MediaLink
+     * @return Builder
+     */
     public Builder stream(MediaLink mediaLink) {
       return set("stream", mediaLink);
     }
     
+    /**
+     * Set the stream MediaLink
+     * @param mediaLink Supplier&lt;MediaLink>
+     * @return Builder
+     */
     public Builder stream(Supplier<? extends MediaLink> mediaLink) {
       return stream(mediaLink.get());
     }
     
+    /**
+     * Get the built AudioVisual object
+     */
     public AudioVisual get() {
       return new AudioVisual(this);
     }
@@ -54,14 +80,24 @@ public final class AudioVisual
     super(builder);
   }
   
+  /**
+   * Get the embedCode property. This should be a snippet of HTML
+   * @return String
+   */
   public String embedCode() {
     return getString("embedCode");
   }
   
+  /**
+   * Get the stream MediaLink or null if not provided
+   * @return MediaLink
+   */
   public MediaLink stream() {
     return this.<MediaLink>get("stream");
   }
   
+  // Java Serialization Support
+  
   Object writeReplace() throws java.io.ObjectStreamException {
     return new SerializedForm(this);
   }

legacy/src/main/java/com/ibm/common/activitystreams/legacy/Binary.java

@@ -35,6 +35,22 @@ import com.google.common.io.BaseEncoding;
 import com.google.common.net.MediaType;
 import com.ibm.common.activitystreams.ASObject;
 
+/**
+ * The legacy "binary" objectType.
+ * 
+ * <pre>
+ *   InputStream in = ...
+ *   // will base64 encode, gzip compress and md5 sum the input data
+ *   // will also set the length property accordingly
+ *   Binary binary = 
+ *     LegacyMakers.binary()
+ *       .gzipData(in)
+ *       .get();
+ * </pre>
+ * 
+ * @author james
+ *
+ */
 public final class Binary
   extends ASObject {
 
@@ -45,20 +61,48 @@ public final class Binary
       objectType("binary");
     }
     
+    /**
+     * Set the input data without any compression. Will automatically
+     * set calculate the md5 sum and length properties
+     * @param in InputStream
+     * @return Builder
+     * @throws IOException
+     */
     public Builder data(
       InputStream in) 
         throws IOException {
       return data(in,null);
     }
     
+    /**
+     * Set the input data with GZip compression. Will automatically
+     * set calculate the md5 sum and length properties
+     * @param in InputStream
+     * @return Builder
+     * @throws IOException
+     */
     public Builder gzipData(InputStream in) throws IOException {
       return data(in, Compression.GZipCompression);
     }
     
+    /**
+     * Set the input data with Deflate compression. Will automatically
+     * set calculate the md5 sum and length properties
+     * @param in InputStream
+     * @return Builder
+     * @throws IOException
+     */
     public Builder deflateData(InputStream in) throws IOException {
       return data(in, Compression.DeflateCompression);
     }
     
+    /**
+     * Set the input data the given Compression. Will automatically
+     * set calculate the md5 sum and length properties
+     * @param in InputStream
+     * @return Builder
+     * @throws IOException
+     */
     public Builder data(
       InputStream in, 
       Compression<?,?> compression) 
@@ -88,19 +132,40 @@ public final class Binary
       return set("data",writer.toString());
     }
     
+    /**
+     * Manually set the md5 properties (this is not recommended. calling the data
+     * methods will automatically generate the md5 checksum for you)
+     * 
+     * @param md5 String
+     * @return Builder
+     */
     public Builder md5(String md5) {
       return set("md5", md5);
     }
     
+    /**
+     * Set the fileUrl property
+     * @param fileUrl String 
+     * @return Builder
+     */
     public Builder fileUrl(String fileUrl) {
       return set("fileUrl", fileUrl);
     }
     
+    /**
+     * Set the MIME Media Type using the Legacy "mimeType" property name
+     * rather than the AS 2.0 "mediaType" property name
+     * @param mt MediaType
+     * @return Builder
+     */
     @Override
     public Builder mediaType(MediaType mt) {
       return set("mimeType", mt);
     }
 
+    /**
+     * Get the built Binary object
+     */
     public Binary get() {
       return new Binary(this);
     }
@@ -111,34 +176,69 @@ public final class Binary
     super(builder);
   }
   
+  /**
+   * Get the fileUrl property
+   * @return String
+   */
   public String fileUrl() {
     return getString("fileUrl");
   }
   
+  /**
+   * Get the length property
+   * @return long
+   */
   public long length() {
     return getLong("length");
   }
   
+  /**
+   * Get the compression property value (typically "gzip" or "deflate")
+   * @return String
+   */
   public String compression() {
     return getString("compression");
   }
   
+  /**
+   * True if compression = gzip
+   * @return boolean
+   */
   public boolean isGzip() {
     return "gzip".equalsIgnoreCase(compression());
   }
   
+  /**
+   * True if compression = deflate
+   * @return boolean
+   */
   public boolean isDeflate() {
     return "deflate".equalsIgnoreCase(compression());
   }
   
+  /**
+   * Return the md5 checksum
+   * @return String
+   */
   public String md5() {
     return getString("md5");
   }
   
+  /**
+   * Return the literal string content of the data property.
+   * This will be base64 encoded and optionally compressed
+   * @return String
+   */
   public String data() {
     return getString("data");
   }
   
+  /**
+   * Return an InputStream for reading the data. Will
+   * decompress and base64 decode as necessary
+   * @return InputStream
+   * @throws IOException
+   */
   public InputStream read() throws IOException {
     Compression<?,?> compression =
       isGzip() ? Compression.GZipCompression :
@@ -147,6 +247,12 @@ public final class Binary
     return read(compression);
   }
   
+  /**
+   * Return an InputStream for reading the data
+   * @param compression Compression
+   * @return InputStream
+   * @throws IOException
+   */
   public InputStream read(Compression<?,?> compression) throws IOException {
     StringReader reader = new StringReader(data());
     InputStream in = BaseEncoding.base64Url().decodingStream(reader);
@@ -157,10 +263,16 @@ public final class Binary
     return in;
   }
 
+  /**
+   * Return the MIME MediaType using the legacy "mimeType" property name
+   * rather than the AS 2.0 "mediaType" name
+   */
   @Override
   public MediaType mediaType() {
     return this.<MediaType>get("mimeType");
   }
+  
+  // Java Serialization Support
  
   Object writeReplace() throws java.io.ObjectStreamException {
     return new SerializedForm(this);

legacy/src/main/java/com/ibm/common/activitystreams/legacy/Bookmark.java

@@ -25,6 +25,10 @@ import java.io.ObjectStreamException;
 
 import com.ibm.common.activitystreams.ASObject;
 
+/**
+ * The legacy "bookmark" objectType
+ * @author james
+ */
 public class Bookmark
   extends ASObject {
 
@@ -35,10 +39,18 @@ public class Bookmark
       objectType("bookmark");
     }
     
+    /**
+     * Set the targetUrl property
+     * @param url String
+     * @return Builder
+     */
     public Builder targetUrl(String url) {
       return set("targetUrl", url);
     }
-    
+
+    /**
+     * Get the built Bookmark object
+     */
     public Bookmark get() {
       return new Bookmark(this);
     }
@@ -49,10 +61,16 @@ public class Bookmark
     super(builder);
   }
   
+  /**
+   * Get the targetUrl property
+   * @return String
+   */
   public String targetUrl() {
     return getString("targetUrl");
   }
   
+  // Java Serialization Support
+  
   Object writeReplace() throws java.io.ObjectStreamException {
     return new SerializedForm(this);
   }

legacy/src/main/java/com/ibm/common/activitystreams/legacy/Compression.java

@@ -29,6 +29,13 @@ import java.util.zip.DeflaterOutputStream;
 import java.util.zip.GZIPInputStream;
 import java.util.zip.GZIPOutputStream;
 
+/**
+ * Compression utility for use with the Binary object
+ * @author james
+ *
+ * @param <O extends OutputStream>
+ * @param <I extends InputStream>
+ */
 public interface Compression<O extends OutputStream, I extends InputStream> {
   String label();
   O compressor(OutputStream wrap) throws IOException;

legacy/src/main/java/com/ibm/common/activitystreams/legacy/Event.java

@@ -27,6 +27,10 @@ import com.google.common.base.Supplier;
 import com.ibm.common.activitystreams.ASObject;
 import com.ibm.common.activitystreams.Collection;
 
+/**
+ * The legacy "event" objectType
+ * @author james
+ */
 public class Event 
   extends ASObject {
 
@@ -36,55 +40,119 @@ public class Event
     Builder() {
       objectType("event");
     }
-    
+ 
+    /**
+     * Set the attendedBy Collection property
+     * @param collection Collection
+     * @return Builder
+     */
     public Builder attendedBy(Collection collection) {
       return set("attendedBy", collection);
     }
     
+    /**
+     * Set the attendedBy Collection property
+     * @param collection Collection
+     * @return Builder
+     */
     public Builder attendedBy(Supplier<? extends Collection> collection) {
       return attendedBy(collection.get());
     }
     
+    /**
+     * Set the attending Collection property
+     * @param collection Collection
+     * @return Builder
+     */
     public Builder attending(Collection collection) {
       return set("attending", collection);
     }
     
+    /**
+     * Set the attending Collection property
+     * @param collection Collection
+     * @return Builder
+     */
     public Builder attending(Supplier<? extends Collection> collection) {
       return attending(collection.get());
     }
     
+    /**
+     * Set the invited Collection property
+     * @param collection Collection
+     * @return Builder
+     */
     public Builder invited(Collection collection) {
       return set("invited", collection);
     }
     
+    /**
+     * Set the invited Collection property
+     * @param collection Collection
+     * @return Builder
+     */
     public Builder invited(Supplier<? extends Collection> collection) {
       return invited(collection.get());
     }
     
+    /**
+     * Set the maybeAttending Collection property
+     * @param collection Collection
+     * @return Builder
+     */
     public Builder maybeAttending(Collection collection) {
       return set("maybeAttending", collection);
     }
     
+    /**
+     * Set the maybeAttending Collection property
+     * @param collection Collection
+     * @return Builder
+     */
     public Builder maybeAttending(Supplier<? extends Collection> collection) {
       return maybeAttending(collection.get());
     }
     
+    /**
+     * Set the notAttendedBy Collection property
+     * @param collection Collection
+     * @return Builder
+     */
     public Builder notAttendedBy(Collection collection) {
       return set("notAttendedBy", collection);
     }
     
+    /**
+     * Set the notAttendedBy Collection property
+     * @param collection Collection
+     * @return Builder
+     */
     public Builder notAttendedBy(Supplier<? extends Collection> collection) {
       return notAttendedBy(collection.get());
     }
     
+    /**
+     * Set the notAttending Collection property
+     * @param collection Collection
+     * @return Builder
+     */
     public Builder notAttending(Collection collection) {
       return set("notAttending", collection);
     }
     
+    /**
+     * Set the notAttending Collection property
+     * @param collection Collection
+     * @return Builder
+     */
     public Builder notAttending(Supplier<? extends Collection> collection) {
       return notAttending(collection.get());
     }
     
+    /**
+     * Get the built Event object
+     * @return Event
+     */
     public Event get() {
       return new Event(this);
     }
@@ -95,30 +163,56 @@ public class Event
     super(builder);
   }
   
+  /**
+   * Get the attendedBy Collection or null if not provided
+   * @return Collection
+   */
   public Collection attendedBy() {
     return this.<Collection>get("attendedBy");
   }
   
+  /**
+   * Get the attending Collection or null if not provided
+   * @return Collection
+   */
   public Collection attending() {
     return this.<Collection>get("attending");
   }
   
+  /**
+   * Get the invited Collection or null if not provided
+   * @return Collection
+   */
   public Collection invited() {
     return this.<Collection>get("invited");
   }
   
+  /**
+   * Get the maybeAttending Collection or null if not provided
+   * @return Collection
+   */
   public Collection maybeAttending() {
     return this.<Collection>get("maybeAttending");
   }
   
+  /**
+   * Get the notAttendedBy Collection or null if not provided
+   * @return Collection
+   */
   public Collection notAttendedBy() {
     return this.<Collection>get("notAttendedBy");
   }
   
+  /**
+   * Get the notAttending Collection or null if not provided
+   * @return Collection
+   */
   public Collection notAttending() {
     return this.<Collection>get("notAttending");
   }
   
+  // Java Serialization Support
+  
   Object writeReplace() throws java.io.ObjectStreamException {
     return new SerializedForm(this);
   }

legacy/src/main/java/com/ibm/common/activitystreams/legacy/File.java

@@ -26,6 +26,10 @@ import java.io.ObjectStreamException;
 import com.google.common.net.MediaType;
 import com.ibm.common.activitystreams.ASObject;
 
+/**
+ * The legacy "file" objectType
+ * @author james
+ */
 public class File
   extends ASObject {
 
@@ -36,15 +40,27 @@ public class File
       objectType("file");
     }
     
+    /**
+     * Set the fileUrl property
+     * @param url String
+     * @return Builder
+     */
     public Builder fileUrl(String url) {
       return set("fileUrl", url);
     }
 
+    /**
+     * Set the MIME mediaType using the legacy "mimeType" property 
+     * name rather than the AS 2.0 "mediaType" property name
+     */
     @Override
     public Builder mediaType(MediaType mt) {
       return set("mimeType", mt);
     }
 
+    /**
+     * Get the built File object
+     */
     public File get() {
       return new File(this);
     }
@@ -55,15 +71,25 @@ public class File
     super(builder);
   }
 
+  /**
+   * Get the MIME mediaType using the legacy "mimeType" property
+   * name rather than the AS 2.0 "mediaType" property
+   */
   @Override
   public MediaType mediaType() {
     return this.<MediaType>get("mimeType");
   }
   
+  /**
+   * Get the fileUrl property
+   * @return
+   */
   public String fileUrl() {
     return getString("fileUrl");
   }
   
+  // Java Serialization Support
+  
   Object writeReplace() throws java.io.ObjectStreamException {
     return new SerializedForm(this);
   }

legacy/src/main/java/com/ibm/common/activitystreams/legacy/Issue.java

@@ -26,6 +26,11 @@ import java.io.ObjectStreamException;
 import com.google.common.collect.ImmutableList;
 import com.ibm.common.activitystreams.ASObject;
 
+/**
+ * The legacy "issue" objectType.
+ * @author james
+ *
+ */
 public class Issue
   extends ASObject {
 
@@ -36,6 +41,12 @@ public class Issue
       objectType("issue");
     }
     
+    /**
+     * Set the "types" property
+     * @param type String
+     * @param types String... optional vararg of additional types to set
+     * @return Builder
+     */
     public Builder types(String type, String... types) {
       ImmutableList.Builder<String> list = 
         ImmutableList.builder();
@@ -46,10 +57,18 @@ public class Issue
       return types(list.build());
     }
     
+    /**
+     * Set the "types" property
+     * @param types Iterable&lt;String>
+     * @return Builder
+     */
     public Builder types(Iterable<String> types) {
       return set("types", types);
     }
     
+    /**
+     * Get the built Issue object
+     */
     public Issue get() {
       return new Issue(this);
     }
@@ -60,10 +79,16 @@ public class Issue
     super(builder);
   }
   
+  /**
+   * Get the listing of types
+   * @return Iterable&lt;String>
+   */
   public Iterable<String> types() {
     return this.<Iterable<String>>get("types");
   }
   
+  // Java Serialization Support `
+  
   Object writeReplace() throws java.io.ObjectStreamException {
     return new SerializedForm(this);
   }

legacy/src/main/java/com/ibm/common/activitystreams/legacy/LegacyMakers.java

@@ -24,6 +24,10 @@ package com.ibm.common.activitystreams.legacy;
 import com.ibm.common.activitystreams.ASObject;
 import static com.ibm.common.activitystreams.Makers.object;
 
+/**
+ * Makers for the various Legacy object types
+ * @author james
+ */
 public final class LegacyMakers {
   
   private LegacyMakers() {}

legacy/src/main/java/com/ibm/common/activitystreams/legacy/LegacyModule.java

@@ -31,7 +31,23 @@ import com.ibm.common.activitystreams.internal.Schema;
 import com.ibm.common.activitystreams.internal.Schema.Builder;
 import com.ibm.common.activitystreams.util.Module;
 
-public class LegacyModule 
+/**
+ * Adds support for legacy objectTypes defined by the original
+ * Activity Streams 1.0 Schema (see https://github.com/activitystreams/activity-schema/blob/master/activity-schema.md)
+ * 
+ * <pre>
+ *   import com.ibm.common.activitystreams.IO;
+ *   import com.ibm.common.activitystreams.legacy.LegacyModule;
+ *   
+ *   //...
+ *   
+ *   IO io = IO.makeDefault(LegacyModule.instance);
+ *   
+ * </pre>
+ * @author james
+ *
+ */
+public final class LegacyModule 
   implements Module {
 
   public static final Module instance = new LegacyModule();

legacy/src/main/java/com/ibm/common/activitystreams/legacy/MediaLink.java

@@ -31,6 +31,11 @@ import com.google.common.collect.ImmutableMap;
 import com.google.common.collect.Maps;
 import com.ibm.common.activitystreams.util.AbstractWritable;
 
+/**
+ * An Activity Streams 1.0 Media Link object. 
+ * @author james
+ *
+ */
 public final class MediaLink
   extends AbstractWritable
   implements Iterable<String>, Serializable {
@@ -42,31 +47,67 @@ public final class MediaLink
     private Map<String,Object> map = 
       Maps.newHashMap();
     
+    /**
+     * When the media link refers to a video or audio resource,
+     * the duration property indicates the total length in seconds
+     * @param duration int
+     * @return Builder
+     */
     public Builder duration(int duration) {
       map.put("duration", duration);
       return this;
     }
     
+    /**
+     * When the media link refers to an object intended to be
+     * displayed visually, such as a video or image, the 
+     * height property specifies the display height in terms
+     * of device independent pixels.
+     * @param height int
+     * @return Builder
+     */
     public Builder height(int height) {
       map.put("height", height);
       return this;
     }
     
+    /**
+     * When the media link refers to an object intended to be
+     * displayed visually, such as a video or image, the 
+     * width property specifies the display width in terms
+     * of device independent pixels.
+     * @param height int
+     * @return Builder
+     */
     public Builder width(int width) {
       map.put("width", width);
       return this;
     }
     
+    /**
+     * The URL of the resource
+     * @param url String
+     * @return Builder
+     */
     public Builder url(String url) {
       map.put("url", url);
       return this;
     }
     
+    /**
+     * Set an arbitrary property on the Media Link
+     * @param key String
+     * @param val Object
+     * @return Builder
+     */
     public Builder set(String key, Object val) {
       map.put(key,val);
       return this;
     }
     
+    /**
+     * Get the built MediaLink object
+     */
     public MediaLink get() {
       return new MediaLink(this);
     }
@@ -80,22 +121,50 @@ public final class MediaLink
     this.map = ImmutableMap.copyOf(builder.map);
   }
   
+  /**
+   * Get the url property
+   * @return
+   */
   public String url() {
     return (String)map.get("url");
   }
   
+  /**
+   * When the media link refers to a video or audio resource,
+   * the duration property indicates the total length in seconds
+   * @return int
+   */
   public int duration() {
     return (Integer)map.get("duration");
   }
   
+  /**
+   * When the media link refers to an object intended to be
+   * displayed visually, such as a video or image, the 
+   * height property specifies the display height in terms
+   * of device independent pixels.
+   * @return int
+   */
   public int height() {
     return (Integer)map.get("height");
   }
   
+  /**
+   * When the media link refers to an object intended to be
+   * displayed visually, such as a video or image, the 
+   * width property specifies the display width in terms
+   * of device independent pixels.
+   * @return int
+   */
   public int width() {
     return (Integer)map.get("width");
   }
   
+  /**
+   * Return the given property
+   * @param key
+   * @return &lt;T>T
+   */
   @SuppressWarnings("unchecked")
   public <T>T get(String key) {
     return (T)map.get(key);
@@ -105,6 +174,8 @@ public final class MediaLink
     return map.keySet().iterator();
   }
   
+  // Java Serialization Support
+  
   Object writeReplace() throws java.io.ObjectStreamException {
     return new SerializedForm(this);
   }

legacy/src/main/java/com/ibm/common/activitystreams/legacy/Membership.java

@@ -27,19 +27,40 @@ import com.google.common.base.Supplier;
 import com.ibm.common.activitystreams.ASObject;
 import com.ibm.common.activitystreams.Collection;
 
+/**
+ * For the legacy "role", "group" and "team" objectTypes.
+ * Membership objects include an additional "members" 
+ * collection property.
+ * 
+ * @author james
+ *
+ */
 public class Membership extends ASObject {
 
   public static final class Builder 
     extends ASObject.AbstractBuilder<Membership, Builder> {
 
+    /**
+     * Set the members collection
+     * @param collection Collection
+     * @return Builder
+     */
     public Builder members(Collection collection) {
       return set("members", collection);
     }
     
+    /**
+     * Set the members collection
+     * @param collection Collection
+     * @return Builder
+     */
     public Builder members(Supplier<? extends Collection> collection) {
       return members(collection.get());
     }
     
+    /**
+     * Get the built Membership object
+     */
     public Membership get() {
       return new Membership(this);
     }
@@ -50,10 +71,16 @@ public class Membership extends ASObject {
     super(builder);
   }
   
+  /**
+   * Return the members collection
+   * @return Collection
+   */
   public Collection members() {
     return this.<Collection>get("members");
   }
   
+  // Java Serialization Support
+  
   Object writeReplace() throws java.io.ObjectStreamException {
     return new SerializedForm(this);
   }

legacy/src/main/java/com/ibm/common/activitystreams/legacy/Question.java

@@ -28,6 +28,18 @@ import com.google.common.base.Supplier;
 import com.ibm.common.activitystreams.ASObject;
 import com.ibm.common.activitystreams.LinkValue;
 
+/**
+ * The legacy "question" object. Question objects
+ * have an additional "options" property that lists
+ * the possible answers to the question.
+ * 
+ * This implementation varies from the Legacy AS 1.0 
+ * model in that it allows AS 2.0 style LinkValues
+ * to be used as the value of the options property.
+ * 
+ * @author james
+ *
+ */
 public class Question extends ASObject {
 
   public static final class Builder 
@@ -37,6 +49,12 @@ public class Question extends ASObject {
       objectType("question");
     }
     
+    /**
+     * Add one or more answers to the question 
+     * @param url String
+     * @param urls String[] optional vararg
+     * @return Builder
+     */
     public Builder option(String url, String... urls) {
       if (url != null)
         link("options", url);
@@ -46,6 +64,12 @@ public class Question extends ASObject {
       return this;
     }
     
+    /**
+     * Add one or more answers to the question 
+     * @param url LinkValue
+     * @param urls LinkValue[] optional vararg
+     * @return Builder
+     */
     public Builder option(LinkValue link, LinkValue... links) {
       if (link != null)
         link("options", link);
@@ -55,10 +79,18 @@ public class Question extends ASObject {
       return this;
     }
     
+    /**
+     * Add an answer to the question
+     * @param link Supplier<? extends LinkValue>
+     * @return Builder
+     */
     public Builder option(Supplier<? extends LinkValue> link) {
       return option(link.get());
     }
     
+    /**
+     * Get the built question object
+     */
     public Question get() {
       return new Question(this);
     }
@@ -69,14 +101,25 @@ public class Question extends ASObject {
     super(builder);
   }
 
+  /**
+   * Get the list of options for the question
+   * @return Iterable&lt;LinkValue>
+   */
   public Iterable<LinkValue> options() {
     return links("options");
   }
-  
+
+  /**
+   * Get the list of options for the question
+   * @param filter Predicate&lt;? super LinkValue>
+   * @return Iterable&lt;LinkValue>
+   */
   public Iterable<LinkValue> options(Predicate<? super LinkValue> filter) {
     return links("options", filter);
   }
   
+  // Java Serialization Support
+  
   Object writeReplace() throws java.io.ObjectStreamException {
     return new SerializedForm(this);
   }

legacy/src/main/java/com/ibm/common/activitystreams/legacy/Task.java

@@ -35,6 +35,12 @@ import com.google.common.base.Supplier;
 import com.ibm.common.activitystreams.ASObject;
 import com.ibm.common.activitystreams.LinkValue;
 
+/**
+ * The Legacy "task" objectType. Task objects in AS 1.0 are essentially
+ * pending Activity statements.
+ * @author james
+ *
+ */
 public class Task 
   extends ASObject {
 
@@ -45,22 +51,48 @@ public class Task
       objectType("task");
     }
     
+    /**
+     * Set the actor
+     * @param actor ASObject
+     * @return Builder
+     */
     public Builder actor(ASObject actor) {
       return set("actor", actor);
     }
     
+    /**
+     * Set the actor
+     * @param actor Supplier<? extends ASObject>
+     * @return Builder
+     */
     public Builder actor(Supplier<? extends ASObject> actor) {
       return actor(actor.get());
     }
     
+    /**
+     * Set the object
+     * @param object ASObject
+     * @return Builder
+     */
     public Builder object(ASObject object) {
       return set("object", object);
     }
     
+    /**
+     * Set the object
+     * @param object Supplier&lt;? extends ASObject>
+     * @return Builder
+     */
     public Builder object(Supplier<? extends ASObject> object) {
       return object(object.get());
     }
     
+    /**
+     * Set one or more prerequisite taskss
+     * @param task Task
+     * @param tasks Task[] optional vararg
+     * @return Builder
+     */
     public Builder prerequisites(Task task, Task... tasks) {
       if (task != null)
         link("prerequisites",task);
@@ -70,10 +102,33 @@ public class Task
       return this;
     }
     
+    /**
+     * Set one or more prerequisite tasks
+     * @param tasks Iterable&lt;Task>
+     * @return Builder
+     */
+    public Builder prerequisites(Iterable<Task> tasks) {
+      if (tasks != null)
+        for (Task task : tasks)
+          link("prerequisites", task);
+      return this;
+    }
+    
+    /**
+     * Set an optional prerequisite
+     * @param task Supplier&lt;? extends Task>
+     * @return Builder
+     */
     public Builder prerequisites(Supplier<? extends Task> task) {
       return prerequisites(task.get());
     }
     
+    /**
+     * Specify one or more other tasks that this task supersedes
+     * @param task Task
+     * @param tasks Task[] optional vararg
+     * @return Builder
+     */
     public Builder supersedes(Task task, Task... tasks) {
       if (task != null)
         link("supersedes",task);
@@ -83,46 +138,115 @@ public class Task
       return this;
     }
     
+    /**
+     * Specify one or more other tasks that this task supersedes
+     * @param tasks Iterable&lt;Task>
+     * @return Builder
+     */
+    public Builder supersedes(Iterable<Task> tasks) {
+      if (tasks != null)
+        for (Task task : tasks)
+          link("supersedes", task);
+      return this;
+    }
+    
+    /**
+     * Specify a task that this task supersedes
+     * @param task Supplier&lt;? extends Task>
+     * @return Builder
+     */
     public Builder supersedes(Supplier<? extends Task> task) {
       return supersedes(task.get());
     }
     
+    /**
+     * Indicates whether this task is required or not
+     * @param on boolean
+     * @return Builder
+     */
     public Builder required(boolean on) {
       return set("required", on);
     }
     
+    /**
+     * Indicates that this task is required
+     * @return Builder
+     */
     public Builder required() {
       return required(true);
     }
     
+    /**
+     * Specifies the verb for this task
+     * @param verb String
+     * @return Builder
+     */
     public Builder verb(String verb) {
       return set("verb", verb);
     }
     
+    /**
+     * Specifies the due date for this task
+     * @param dt DateTime
+     * @return Builder
+     */
     public Builder by(DateTime dt) {
       return this._dt("by", dt);
     }
     
+    /**
+     * Specifies that this task is due right now
+     * @return Builder
+     */
     public Builder byNow() {
       return this._dtNow("by");
     }
     
+    /**
+     * Specifies the due date for this task in terms of a specific
+     * duration of time from right now
+     * @param duration ReadableDuration
+     * @return Builder
+     */
     public Builder byFromNow(ReadableDuration duration) {
       return this._dtFromNow("by", duration);
     }
     
+    /**
+     * Specifies the due date for this task in terms of a specific
+     * period of time from right now
+     * @param period ReadablePeriod
+     * @return Builder
+     */
     public Builder byFromNow(ReadablePeriod period) {
       return this._dtFromNow("by", period);
     }
     
+    /**
+     * Specifies the due date for this task in terms of a specific
+     * duration of time from the given instant;
+     * @param dt DateTime
+     * @param duration ReadableDuration
+     * @return Builder
+     */
     public Builder by(DateTime dt, ReadableDuration duration) {
       return this._dtFrom("by", dt, duration);
     }
     
+    /**
+     * Specifies the due date for this task in terms of a specific
+     * period of time from the given instant
+     * @param dt DateTime
+     * @param period ReadablePeriod
+     * @return Builder
+     */
     public Builder by(DateTime dt, ReadablePeriod period) {
       return this._dtFrom("by", dt, period);
     }
     
+    /**
+     * Get the completed Task object
+     */
     public Task get() {
       return new Task(this);
     }
@@ -133,30 +257,62 @@ public class Task
     super(builder);
   }
   
+  /**
+   * Get the actor
+   * @return &lt;A extends ASObject>A
+   */
   public <A extends ASObject>A actor() {
     return this.<A>get("actor");
   }
   
+  /**
+   * Get the object
+   * @return &lt;A extends ASObject>A
+   */
   public <A extends ASObject>A object() {
     return this.<A>get("object");
   }
   
+  /**
+   * Get the due date
+   * @return DateTime
+   */
   public DateTime by() {
     return getDateTime("by");
   }
   
+  /**
+   * Get the verb
+   * @return String
+   */
   public String verb() {
     return getString("verb");
   }
   
+  /**
+   * Return true if this task is required
+   * @return boolean
+   */
   public boolean required() {
     return getBoolean("required");
   }
   
+  /**
+   * Return the listing of other tasks superseded by this one
+   * (will return an empty iterable if there are no superseded
+   * tasks)
+   * @return Iterable&lt;Task>
+   */
   public Iterable<Task> supersedes() {
     return transform(links("supersedes",filter), transformer);
   }
   
+  /**
+   * Return the listing of other tasks upon which this task depends.
+   * (will return an empty iterable if there are no prerequisite
+   * tasks)
+   * @return Iterable&lt;Task>
+   */
   public Iterable<Task> prerequisites() {
     return transform(links("prerequisites",filter), transformer);
   }
@@ -176,6 +332,8 @@ public class Task
     
   };
   
+  // Java Serialization Support
+  
   Object writeReplace() throws java.io.ObjectStreamException {
     return new SerializedForm(this);
   }

legacy/src/main/java/com/ibm/common/activitystreams/legacy/WithImage.java

@@ -26,15 +26,33 @@ import java.io.ObjectStreamException;
 import com.google.common.base.Supplier;
 import com.ibm.common.activitystreams.ASObject;
 
+/**
+ * For the legacy "product" and "image" objectTypes. These
+ * include an additional "fullImage" property whose value
+ * is a MediaLink.
+ * 
+ * @author james
+ *
+ */
 public class WithImage extends ASObject {
 
   public static final class Builder 
     extends ASObject.AbstractBuilder<WithImage, Builder> {
 
+    /**
+     * Set the fullImage property
+     * @param link MediaLink
+     * @return Builder
+     */
     public Builder fullImage(MediaLink link) {
       return set("fullImage", link);
     }
     
+    /**
+     * Set the fullImage property
+     * @param link Supplier&lt;? extends MediaLink>
+     * @return Builder
+     */
     public Builder fullImage(Supplier<? extends MediaLink> link) {
       return fullImage(link.get());
     }
@@ -49,10 +67,16 @@ public class WithImage extends ASObject {
     super(builder);
   }
   
+  /**
+   * Get the fullImage property
+   * @return MediaLink
+   */
   public MediaLink fullImage() {
     return this.<MediaLink>get("fullImage");
   }
   
+  // Java Serialization Support
+  
   Object writeReplace() throws java.io.ObjectStreamException {
     return new SerializedForm(this);
   }