Improve docs of water and water_name

layers/water/water.yaml

@@ -2,14 +2,21 @@ layer:
   id: "water"
   description: |
       Water polygons representing oceans and lakes. Covered watered areas are excluded (`covered=yes`).
-      Until z6 all water originates from Natural Earth. To get a more correct display of the south pole you should also
+      On low zoom levels all water originates from Natural Earth. To get a more correct display of the south pole you should also
       style the covering ice shelves over the water.
-      Water from OpenStreetMap after z7 is split into many smaller polygons to improve rendering performance.
+      On higher zoom levels water polygons from [OpenStreetMapData](http://openstreetmapdata.com/) are used.
+      The polygons are split into many smaller polygons to improve rendering performance.
       This however can lead to less rendering options in clients since these boundaries show up. So you might not be
       able to use border styling for ocean water features.
   fields:
-    class: |
+    class:
-        Either `ocean`, `lake` or `river`.
+      description: |
+          All water polygons from [OpenStreetMapData](http://openstreetmapdata.com/) have the class `ocean`.
+          Water bodies are classified as `lake` or `river` for water bodies with the [`waterway`](http://wiki.openstreetmap.org/wiki/Key:waterway) tag.
+      values:
+      - ocean
+      - lake
+      - river
   buffer_size: 4
   datasource:
     query: (SELECT geometry, class FROM layer_water(!bbox!, z(!scale_denominator!))) AS t

layers/water_name/water_name.yaml

@@ -7,8 +7,11 @@ layer:
   fields:
     name: The OSM [`name`](http://wiki.openstreetmap.org/wiki/Key:name) value of the water body.
     name_en: The english `name:en` value if available.
-    class: |
+    class:
-        At the moment only `lake` since no ocean parts are labelled. *Reserved for future use*.
+      description: |
+          At the moment only `lake` since no ocean parts are labelled. *Reserved for future use*.
+      values:
+      - lake
   buffer_size: 8
   srs: +proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0.0 +k=1.0 +units=m +nadgrids=@null +wktext +no_defs +over
   datasource: