Add more docs

src/ol/layer/WebGLTile.js

@@ -18,7 +18,10 @@ import {assign} from '../obj.js';
  * @typedef {Object} Style
  * Translates tile data to rendered pixels.
  *
- * @property {Object<string, number>} [variables] Style variables.  Each variable must hold a number.
+ * @property {Object<string, number>} [variables] Style variables.  Each variable must hold a number.  These
+ * variables can be used in the `color`, `brightness`, `contrast`, `exposure`, `saturation` and `gamma`
+ * {@link import("../style/expressions.js").ExpressionValue expressions}, using the `['var', 'varName']` operator.
+ * To update style variables, use the {@link import("./WebGLTile.js").default#updateStyleVariables} method.
  * @property {import("../style/expressions.js").ExpressionValue} [color] An expression applied to color values.
  * @property {import("../style/expressions.js").ExpressionValue} [brightness=0] Value used to decrease or increase
  * the layer brightness.  Values range from -1 to 1.
@@ -290,6 +293,7 @@ class WebGLTileLayer extends BaseTileLayer {
   /**
    * Update any variables used by the layer style and trigger a re-render.
    * @param {Object<string, number>} variables Variables to update.
+   * @api
    */
   updateStyleVariables(variables) {
     assign(this.styleVariables_, variables);

src/ol/source/DataTile.js

@@ -14,6 +14,7 @@ import {getUid} from '../util.js';
 /**
  * @typedef {Object} Options
  * @property {function(number, number, number) : Promise<import("../DataTile.js").Data>} [loader] Data loader.  Called with z, x, and y tile coordinates.
+ * Returns a promise that resolves to a {@link import("../DataTile.js").Data}.
  * @property {number} [maxZoom=42] Optional max zoom level. Not used if `tileGrid` is provided.
  * @property {number} [minZoom=0] Optional min zoom level. Not used if `tileGrid` is provided.
  * @property {number|import("../size.js").Size} [tileSize=[256, 256]] The pixel width and height of the tiles.
@@ -30,9 +31,10 @@ import {getUid} from '../util.js';
 
 /**
  * @classdesc
- * Base class for sources providing tiles divided into a tile grid over http.
+ * Base class for sources providing tiles divided into a tile grid.
  *
  * @fires import("./Tile.js").TileSourceEvent
+ * @api
  */
 class DataTileSource extends TileSource {
   /**

src/ol/source/GeoTIFF.js

@@ -11,8 +11,8 @@ import {get as getProjection} from '../proj.js';
 import {toSize} from '../size.js';
 
 /**
- * @typedef SourceInfo
+ * @typedef {Object} SourceInfo
- * @property {string} url URL for the source.
+ * @property {string} url URL for the source GeoTIFF.
  * @property {Array<string>} [overviews] List of any overview URLs.
  * @property {number} [min=0] The minimum source data value.  Rendered values are scaled from 0 to 1 based on
  * the configured min and max.
@@ -21,7 +21,8 @@ import {toSize} from '../size.js';
  * @property {number} [nodata] Values to discard. When provided, an additional band (alpha) will be added
  * to the data.
  * @property {Array<number>} [bands] Indices of the bands to be read from. If not provided, all bands will
- * be read.
+ * be read. If, for example, a GeoTIFF has red, green, blue and near-infrared bands and you only need the
+ * infrared band, configure `bands: [3]`.
  */
 
 let workerPool;
@@ -137,20 +138,25 @@ function getMaxForDataType(array) {
 }
 
 /**
- * @typedef Options
+ * @typedef {Object} Options
  * @property {Array<SourceInfo>} sources List of information about GeoTIFF sources.
- * When using multiple sources, each source must be a single-band source, or the `samples`
+ * Multiple sources can be combined when their resolution sets are equal after applying a scale.
- * option must be configured with a single sample index for each source. Multiple sources
+ * The list of sources defines a mapping between input bands as they are read from each GeoTIFF, and
- * can only be combined when their resolution sets are equal after applying a scale.
+ * the output bands that are provided by data tiles. To control which bands to read from each GeoTIFF,
+ * use the {@link import("./GeoTIFF.js").SourceInfo bands} property. If, for example, you spedify two
+ * sources, one with 3 bands and {@link import("./GeoTIFF.js").SourceInfo nodata} configured, and
+ * another with 1 band, the resulting data tiles will have 5 bands: 3 from the first source, 1 alpha
+ * band from the first source, and 1 band from the second source.
  */
 
 /**
  * @classdesc
  * A source for working with GeoTIFF data.
+ * @api
  */
 class GeoTIFFSource extends DataTile {
   /**
-   * @param {Options} options Image tile options.
+   * @param {Options} options Data tile options.
    */
   constructor(options) {
     super({

src/ol/style/expressions.js

@@ -7,17 +7,23 @@ import {asArray, isStringColor} from '../color.js';
 
 /**
  * Base type used for literal style parameters; can be a number literal or the output of an operator,
- * which in turns takes {@link ExpressionValue} arguments.
+ * which in turns takes {@link import("./expressions.js").ExpressionValue} arguments.
  *
  * The following operators can be used:
  *
  * * Reading operators:
+ *   * `['band', bandIndex]` fetches a pixel value from band `bandIndex` of the source's data. The first
+ *     `bandIndex` of the source data is `1`. Fetched values are in the 0..1 range.
+ *     {@link import("../source/TileImage.js").default} sources have 4 bands: red, green, blue and alpha.
+ *     {@link import("../source/DataTile.js").default} sources can have any number of bands, depending on
+ *     the underlying data source and
+ *     {@link import("../source/GeoTIFF.js").Options configuration}.
  *   * `['get', 'attributeName']` fetches a feature attribute (it will be prefixed by `a_` in the shader)
  *     Note: those will be taken from the attributes provided to the renderer
- *   * `['var', 'varName']` fetches a value from the style variables, or 0 if undefined
- *   * `['time']` returns the time in seconds since the creation of the layer
- *   * `['zoom']` returns the current zoom level
  *   * `['resolution']` returns the current resolution
+ *   * `['time']` returns the time in seconds since the creation of the layer
+ *   * `['var', 'varName']` fetches a value from the style variables, or 0 if undefined
+ *   * `['zoom']` returns the current zoom level
  *
  * * Math operators:
  *   * `['*', value1, value2]` multiplies `value1` by `value2`