Merge pull request openlayers#2378 from pagameba/doc-feature

Improve documentation for ol.Feature

src/ol/feature.js

@@ -17,18 +17,46 @@ goog.require('ol.style.Style');
 
 /**
  * @classdesc
- * A vector object for geographical features with a geometry and other
+ * A vector object for geographic features with a geometry and other
  * attribute properties, similar to the features in vector file formats like
  * GeoJSON.
+ *
  * Features can be styled individually or use the style of their vector layer.
- * Note that attribute properties are set as {@link ol.Object} properties on the
- * feature object, so they are observable, and have get/set accessors.
+ * Note that attribute properties are set as {@link ol.Object} properties on
+ * the feature object, so they are observable, and have get/set accessors.
+ *
+ * Typically, a feature has a single geometry property. You can set the
+ * geometry using the `setGeometry` method and get it with `getGeometry`.
+ * It is possible to store more than one geometry on a feature using attribute
+ * properties. By default, the geometry used for rendering is identified by
+ * the property name `geometry`. If you want to use another geometry property
+ * for rendering, use the `setGeometryName` method to change the attribute
+ * property associated with the geometry for the feature.  For example:
+ *
+ * ```js
+ * var feature = new ol.Feature({
+ *   geometry: new ol.geom.Polygon(polyCoords),
+ *   labelPoint: new ol.geom.Point(labelCoords),
+ *   name: 'My Polygon'
+ * });
+ *
+ * // get the polygon geometry
+ * var poly = feature.getGeometry();
+ *
+ * // Render the feature as a point using the coordinates from labelPoint
+ * feature.setGeometryName('labelPoint');
+ *
+ * // get the point geometry
+ * var point = feature.getGeometry();
+ * ```
  *
  * @constructor
  * @extends {ol.Object}
  * @fires change Triggered when the geometry or style of the feature changes.
  * @param {ol.geom.Geometry|Object.<string, *>=} opt_geometryOrProperties
- *     Geometry or properties.
+ *     You may pass a Geometry object directly, or an object literal
+ *     containing properties.  If you pass an object literal, you may
+ *     include a Geometry associated with a `geometry` key.
  * @api
  */
 ol.Feature = function(opt_geometryOrProperties) {
@@ -109,7 +137,10 @@ ol.Feature.prototype.clone = function() {
 
 
 /**
- * @return {ol.geom.Geometry|undefined} Geometry.
+ * @return {ol.geom.Geometry|undefined} Returns the Geometry associated
+ *     with this feature using the current geometry name property.  By
+ *     default, this is `geometry` but it may be changed by calling
+ *     `setGeometryName`.
  * @api
  * @observable
  */
@@ -133,7 +164,9 @@ ol.Feature.prototype.getId = function() {
 
 
 /**
- * @return {string} Geometry property name.
+ * @return {string} Get the property name associated with the geometry for
+ *     this feature.  By default, this is `geometry` but it may be changed by
+ *     calling `setGeometryName`.
  * @api
  */
 ol.Feature.prototype.getGeometryName = function() {
@@ -143,7 +176,9 @@ ol.Feature.prototype.getGeometryName = function() {
 
 /**
  * @return {ol.style.Style|Array.<ol.style.Style>|
- *     ol.feature.FeatureStyleFunction} User provided style.
+ *     ol.feature.FeatureStyleFunction} Return the style provided in the
+ *     constructor options or the last call to setStyle in the same format
+ *     that it was provided in.
  * @api
  */
 ol.Feature.prototype.getStyle = function() {
@@ -152,7 +187,8 @@ ol.Feature.prototype.getStyle = function() {
 
 
 /**
- * @return {ol.feature.FeatureStyleFunction|undefined} Style function.
+ * @return {ol.feature.FeatureStyleFunction|undefined} Return a function
+ * representing the current style of this feature.
  * @api
  */
 ol.Feature.prototype.getStyleFunction = function() {
@@ -186,7 +222,10 @@ ol.Feature.prototype.handleGeometryChanged_ = function() {
 
 
 /**
- * @param {ol.geom.Geometry|undefined} geometry Geometry.
+ * @param {ol.geom.Geometry|undefined} geometry Set the geometry for this
+ * feature. This will update the property associated with the current
+ * geometry property name.  By default, this is `geometry` but it can be
+ * changed by calling `setGeometryName`.
  * @api
  * @observable
  */
@@ -201,7 +240,7 @@ goog.exportProperty(
 
 /**
  * @param {ol.style.Style|Array.<ol.style.Style>|
- *     ol.feature.FeatureStyleFunction} style Feature style.
+ *     ol.feature.FeatureStyleFunction} style Set the style for this feature.
  * @api
  */
 ol.Feature.prototype.setStyle = function(style) {
@@ -212,7 +251,9 @@ ol.Feature.prototype.setStyle = function(style) {
 
 
 /**
- * @param {number|string|undefined} id Id.
+ * @param {number|string|undefined} id Set a unique id for this feature.
+ * The id may be used to retrieve a feature from a vector source with the
+ * {@link ol.source.Vector#getFeatureById} method.
  * @api
  */
 ol.Feature.prototype.setId = function(id) {
@@ -222,7 +263,8 @@ ol.Feature.prototype.setId = function(id) {
 
 
 /**
- * @param {string} name Geometry property name.
+ * @param {string} name Set the property name from which this feature's
+ *     geometry will be fetched when calling `getGeometry`.
  * @api
  */
 ol.Feature.prototype.setGeometryName = function(name) {