mprove mapbox.style description (take 3)

Author: etpinard

src/plots/mapbox/layout_attributes.js

@@ -51,17 +51,26 @@ var attrs = module.exports = overrideAll({
         dflt: constants.styleValueDflt,
         role: 'style',
         description: [
-            'Sets the base map style.',
-            'Base map styles are rendered below all traces and layout layers.',
-            'Base map styles can include multiple layers.',
-            'Either input one of the default Mapbox style names: ', constants.styleValuesMapbox.join(', '), '.',
-            'Note that to use these, a Mapbox access token must be set either in the `accesstoken` attribute',
+            'Defines the map layers that are rendered by default below the trace layers defined in `data`,',
+            'which are themselves by default rendered below the layers defined in `layout.mapbox.layers`.',
+            '',
+            'These layers can be defined either explicitly as a Mapbox Style object which can contain multiple',
+            'layer definitions that load data from any public or private Tile Map Service (TMS or XYZ) or Web Map Service (WMS)',
+            'or implicitly by using one of the built-in style objects which use WMSes which do not require any',
+            'access tokens, or by using a default Mapbox style or custom Mapbox style URL, both of',
+            'which require a Mapbox access token',
+            '',
+            'Note that Mapbox access token can be set in the `accesstoken` attribute',
             'or in the `mapboxAccessToken` config option.',
-            'For OpenStreetMap raster tiles, use: ', constants.styleValueOSM, '.',
-            'No access token is required to render the', constants.styleValueOSM, 'style.',
-            'One can also set `style` as a URL to a Mapbox custom style, e.g. created in Mapbox Studio.',
-            'Finally, one can set `style` as a Mapbox style JSON, see',
-            'https://docs.mapbox.com/mapbox-gl-js/style-spec for more info.'
+            '',
+            'Mapbox Style objects are of the form described in the Mapbox GL JS documentation available at',
+            'https://docs.mapbox.com/mapbox-gl-js/style-spec',
+            '',
+            'The built-in plotly.js styles objects are:', constants.styleValuesNonMapbox.join(', '),
+            '',
+            'The built-in Mapbox styles are:', constants.styleValuesMapbox.join(', '),
+            '',
+            'Mapbox style URLs are of the form: mapbox://mapbox.mapbox-<name>-<version>'
         ].join(' ')
     },