Documentation of Geometry usage/

lib/data-types.js

@@ -816,7 +816,53 @@ var helpers = {
 };
 
 /**
- * A geometry datatype represents two dimensional spacial objects.
+ * A column storing Geometry information.  
+ *
+ * Only available in PostgreSQL (with PostGIS) or MySQL.  
+ * In MySQL, allowable Geometry types are 'POINT', 'LINESTRING', 'POLYGON'.
+ *
+ * When using, GeoJSON is accepted as input and returned as output.  
+ * In PostGIS, the GeoJSON is parsed using the PostGIS function `ST_GeomFromGeoJSON`.  
+ * In MySQL it is parsed using the function `GeomFromText`.  
+ * Therefore, one can just follow the [GeoJSON spec](http://geojson.org/geojson-spec.html) for handling geometry objects.  See the following examples:
+ *
+ * ```js
+ * // Create a new point:
+ * var point = { type: 'Point', coordinates: [39.807222,-76.984722]};
+ * 
+ * User.create({username: 'username', geometry: point }).then(function(newUser) {
+ * ...
+ * });
+ * 
+ * // Create a new linestring:
+ * var line = { type: 'LineString', 'coordinates': [ [100.0, 0.0], [101.0, 1.0] ] };
+ * 
+ * User.create({username: 'username', geometry: line }).then(function(newUser) {
+ * ...
+ * });
+ * 
+ * // Create a new polygon:
+ * var polygon = { type: 'Polygon', coordinates: [
+ *                 [ [100.0, 0.0], [101.0, 0.0], [101.0, 1.0],
+ *                   [100.0, 1.0], [100.0, 0.0] ] 
+ *                 ]};
+ * 
+ * User.create({username: 'username', geometry: polygon }).then(function(newUser) {
+ * ...
+ * });
+
+ * // Create a new point with a custom SRID:
+ * var point = { 
+ *   type: 'Point', 
+ *   coordinates: [39.807222,-76.984722],
+ *   crs: { type: 'name', properties: { name: 'EPSG:4326'} }
+ * };
+ * 
+ * User.create({username: 'username', geometry: point }).then(function(newUser) {
+ * ...
+ * });
+ * ```
+ *
  * @property GEOMETRY
  */