document the layer object's properties in addLayer (#9571)

src/ui/map.js

@@ -1751,15 +1751,51 @@ class Map extends Camera {
      * A layer defines how data from a specified source will be styled. Read more about layer types
      * and available paint and layout properties in the [Mapbox Style Specification](https://docs.mapbox.com/mapbox-gl-js/style-spec/#layers).
      *
-     * @param {Object | CustomLayerInterface} layer The style layer to add, conforming to the Mapbox Style Specification's
-     *   [layer definition](https://docs.mapbox.com/mapbox-gl-js/style-spec/#layers).
+     * @param {Object | CustomLayerInterface} layer The layer to add, conforming to either the Mapbox Style Specification's [layer definition](https://docs.mapbox.com/mapbox-gl-js/style-spec/#layers) or, less commonly, the [`CustomLayerInterface`](https://docs.mapbox.com/mapbox-gl-js/api/#customlayerinterface) specification.
+     * The Mapbox Style Specification's layer definition is appropriate for most layers.
+     *
+     * @param {string} layer.id A unique idenfier that you define.
+     * @param {string} layer.type The type of layer (for example `fill` or `symbol`).
+     * A list of layer types is available in the [Mapbox Style Specification](https://docs.mapbox.com/mapbox-gl-js/style-spec/layers/#type).
+     *
+     * (This can also be `custom`. For more information, see [`CustomLayerInterface`](https://docs.mapbox.com/mapbox-gl-js/api/#customlayerinterface).)
+     * @param {string | Object} [layer.source] The data source for the layer.
+     * Reference a source that has _already been defined_ using the source's unique id.
+     * Reference a _new source_ using a source object (as defined in the [Mapbox Style Specification](https://docs.mapbox.com/mapbox-gl-js/style-spec/sources/)) directly.
+     * This is **required** for all `layer.type` options _except_ for `custom`.
+     * @param {string} [layer.sourceLayer] (optional) The name of the [source layer](https://docs.mapbox.com/help/glossary/source-layer/) within the specified `layer.source` to use for this style layer.
+     * This is only applicable for vector tile sources and is **required** when `layer.source` is of the type `vector`.
+     * @param {array} [layer.filter] (optional) An expression specifying conditions on source features.
+     * Only features that match the filter are displayed.
+     * The Mapbox Style Specification includes more information on the limitations of the [`filter`](https://docs.mapbox.com/mapbox-gl-js/style-spec/layers/#filter) parameter
+     * and a complete list of available [expressions](https://docs.mapbox.com/mapbox-gl-js/style-spec/expressions/).
+     * If no filter is provided, all features in the source (or source layer for vector tilesets) will be displayed.
+     * @param {Object} [layer.paint] (optional) Paint properties for the layer.
+     * Available paint properties vary by `layer.type`.
+     * A full list of paint properties for each layer type is available in the [Mapbox Style Specification](https://docs.mapbox.com/mapbox-gl-js/style-spec/layers/).
+     * If no paint properties are specified, default values will be used.
+     * @param {Object} [layer.layout] (optional) Layout properties for the layer.
+     * Available layout properties vary by `layer.type`.
+     * A full list of layout properties for each layer type is available in the [Mapbox Style Specification](https://docs.mapbox.com/mapbox-gl-js/style-spec/layers/).
+     * If no layout properties are specified, default values will be used.
+     * @param {number} [layer.maxzoom] (optional) The maximum zoom level for the layer.
+     * At zoom levels equal to or greater than the maxzoom, the layer will be hidden.
+     * The value can be any number between `0` and `24` (inclusive).
+     * If no maxzoom is provided, the layer will be visible at all zoom levels for which there are tiles available.
+     * @param {number} [layer.minzoom] (optional) The minimum zoom level for the layer.
+     * At zoom levels less than the minzoom, the layer will be hidden.
+     * The value can be any number between `0` and `24` (inclusive).
+     * If no minzoom is provided, the layer will be visible at all zoom levels for which there are tiles available.
+     * @param {Object} [layer.metadata] (optional) Arbitrary properties useful to track with the layer, but do not influence rendering.
+     * @param {string} [layer.renderingMode] This is only applicable for layers with the type `custom`.
+     * See [`CustomLayerInterface`](https://docs.mapbox.com/mapbox-gl-js/api/#customlayerinterface) for more information.
      * @param {string} [beforeId] The ID of an existing layer to insert the new layer before.
-     *   If this argument is omitted, the layer will be appended to the end of the layers array.
+     * If this argument is not specified, the layer will be appended to the end of the layers array.
      *
      * @returns {Map} `this`
      *
      * @example
-     * // Add a circle layer with a vector source.
+     * // Add a circle layer with a vector source
      * map.addLayer({
      *   id: 'points-of-interest',
      *   source: {
@@ -1776,9 +1812,44 @@ class Map extends Camera {
      *   }
      * });
      *
-     * @see [Create and style clusters](https://www.mapbox.com/mapbox-gl-js/example/cluster/)
-     * @see [Add a vector tile source](https://www.mapbox.com/mapbox-gl-js/example/vector-source/)
-     * @see [Add a WMS source](https://www.mapbox.com/mapbox-gl-js/example/wms/)
+     * @example
+     * // Define a source before using it to create a new layer
+     * map.addSource('state-data', {
+     *   type: 'geojson',
+     *   data: 'path/to/data.geojson'
+     * });
+     *
+     * map.addLayer({
+     *   id: 'states',
+     *   // References the GeoJSON source defined above
+     *   // and does not require a `source-layer`
+     *   source: 'state-data',
+     *   type: 'symbol',
+     *   layout: {
+     *     // Set the label content to the
+     *     // feature's `name` property
+     *     text-field: ['get', 'name']
+     *   }
+     * });
+     *
+     * @example
+     * // Add a new symbol layer before an existing layer
+     * map.addLayer({
+     *   id: 'states',
+     *   // References a source that's already been defined
+     *   source: 'state-data',
+     *   type: 'symbol',
+     *   layout: {
+     *     // Set the label content to the
+     *     // feature's `name` property
+     *     text-field: ['get', 'name']
+     *   }
+     * // Add the layer before the existing `cities` layer
+     * }, 'cities');
+     *
+     * @see [Create and style clusters](https://docs.mapbox.com/mapbox-gl-js/example/cluster/)
+     * @see [Add a vector tile source](https://docs.mapbox.com/mapbox-gl-js/example/vector-source/)
+     * @see [Add a WMS source](https://docs.mapbox.com/mapbox-gl-js/example/wms/)
      */
     addLayer(layer: LayerSpecification | CustomLayerInterface, beforeId?: string) {
         this._lazyInitEmptyStyle();