From bf3770a9da4453db7f67108ae0e728038c24e1ce Mon Sep 17 00:00:00 2001
From: Peter Robins <github@peterrobins.co.uk>
Date: Thu, 31 Jul 2014 17:47:31 +0000
Subject: [PATCH] Improve docs for style

---
 externs/olx.js              |  9 +++--
 src/ol/feature.js           | 10 +++--
 src/ol/style.jsdoc          | 77 +++++++++++++++++++++++++++++++++++++
 src/ol/style/strokestyle.js |  3 ++
 4 files changed, 92 insertions(+), 7 deletions(-)

diff --git a/externs/olx.js b/externs/olx.js
index 8ada72db1a..b54ce4b2ed 100644
--- a/externs/olx.js
+++ b/externs/olx.js
@@ -2601,7 +2601,8 @@ olx.layer.VectorOptions.prototype.source;
 
 
 /**
- * Layer style.
+ * Layer style. See {@link ol.style} for default style which will be used if
+ * this is not defined.
  * @type {ol.style.Style|Array.<ol.style.Style>|ol.style.StyleFunction|undefined}
  */
 olx.layer.VectorOptions.prototype.style;
@@ -4602,7 +4603,8 @@ olx.style.FillOptions;
 
 
 /**
- * Color.
+ * Color. Default null; if null, the Canvas/renderer default black will be
+ * used.
  * @type {ol.Color|string|undefined}
  */
 olx.style.FillOptions.prototype.color;
@@ -4754,7 +4756,8 @@ olx.style.StrokeOptions;
 
 
 /**
- * Color.
+ * Color. Default null; if null, the Canvas/renderer default black will be
+ * used.
  * @type {ol.Color|string|undefined}
  */
 olx.style.StrokeOptions.prototype.color;
diff --git a/src/ol/feature.js b/src/ol/feature.js
index fd48539f50..3dd74b8143 100644
--- a/src/ol/feature.js
+++ b/src/ol/feature.js
@@ -21,7 +21,9 @@ goog.require('ol.style.Style');
  * 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.
+ * Features can be styled individually with `setStyle`; otherwise they use the
+ * style of their vector layer or feature overlay.
+ *
  * Note that attribute properties are set as {@link ol.Object} properties on
  * the feature object, so they are observable, and have get/set accessors.
  *
@@ -176,9 +178,9 @@ ol.Feature.prototype.getGeometryName = function() {
 
 /**
  * @return {ol.style.Style|Array.<ol.style.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.
+ *     ol.feature.FeatureStyleFunction} Return the style as set by setStyle in
+ *     the same format that it was provided in. If setStyle has not been run,
+ *     return `undefined`.
  * @api
  */
 ol.Feature.prototype.getStyle = function() {
diff --git a/src/ol/style.jsdoc b/src/ol/style.jsdoc
index ed02b4dbdf..2386a1007e 100644
--- a/src/ol/style.jsdoc
+++ b/src/ol/style.jsdoc
@@ -1,3 +1,80 @@
 /**
+ * Feature styles.
+ *
+ * If no style is defined, the following default style is used:
+ * ```js
+ *  var fill = new ol.style.Fill({
+ *    color: 'rgba(255,255,255,0.4)'
+ *  });
+ *  var stroke = new ol.style.Stroke({
+ *    color: '#3399CC',
+ *    width: 1.25
+ *  });
+ *  var styles = [
+ *    new ol.style.Style({
+ *      image: new ol.style.Circle({
+ *        fill: fill,
+ *        stroke: stroke,
+ *        radius: 5
+ *      }),
+ *      fill: fill,
+ *      stroke: stroke
+ *    })
+ *  ];
+ * ```
+ *
+ * A separate editing style has the following defaults:
+ * ```js
+ *  var white = [255, 255, 255, 1];
+ *  var blue = [0, 153, 255, 1];
+ *  var width = 3;
+ *  styles[ol.geom.GeometryType.POLYGON] = [
+ *    new ol.style.Style({
+ *      fill: new ol.style.Fill({
+ *        color: [255, 255, 255, 0.5]
+ *      })
+ *    })
+ *  ];
+ *  styles[ol.geom.GeometryType.MULTI_POLYGON] =
+ *      styles[ol.geom.GeometryType.POLYGON];
+ *  styles[ol.geom.GeometryType.LINE_STRING] = [
+ *    new ol.style.Style({
+ *      stroke: new ol.style.Stroke({
+ *        color: white,
+ *        width: width + 2
+ *      })
+ *    }),
+ *    new ol.style.Style({
+ *      stroke: new ol.style.Stroke({
+ *        color: blue,
+ *        width: width
+ *      })
+ *    })
+ *  ];
+ *  styles[ol.geom.GeometryType.MULTI_LINE_STRING] =
+ *      styles[ol.geom.GeometryType.LINE_STRING];
+ *  styles[ol.geom.GeometryType.POINT] = [
+ *    new ol.style.Style({
+ *      image: new ol.style.Circle({
+ *        radius: width * 2,
+ *        fill: new ol.style.Fill({
+ *          color: blue
+ *        }),
+ *        stroke: new ol.style.Stroke({
+ *          color: white,
+ *          width: width / 2
+ *        })
+ *      }),
+ *      zIndex: Infinity
+ *    })
+ *  ];
+ *  styles[ol.geom.GeometryType.MULTI_POINT] =
+ *      styles[ol.geom.GeometryType.POINT];
+ *  styles[ol.geom.GeometryType.GEOMETRY_COLLECTION] =
+ *      styles[ol.geom.GeometryType.POLYGON].concat(
+ *          styles[ol.geom.GeometryType.POINT]
+ *      );
+ *```
+ *
  * @namespace ol.style
  */
diff --git a/src/ol/style/strokestyle.js b/src/ol/style/strokestyle.js
index 3c44fe2ddf..c5d2e90c91 100644
--- a/src/ol/style/strokestyle.js
+++ b/src/ol/style/strokestyle.js
@@ -7,6 +7,9 @@ goog.require('ol.color');
 /**
  * @classdesc
  * Set stroke style for vector features.
+ * Note that the defaults given are the Canvas defaults, which will be used if
+ * option is not defined. The `get` functions return whatever was entered in
+ * the options; they will not return the default.
  *
  * @constructor
  * @param {olx.style.StrokeOptions=} opt_options Options.