Improve documentation on webgl and View

src/ol/View.js

@@ -191,6 +191,11 @@ const DEFAULT_MIN_ZOOM = 0;
  * This is the object to act upon to change the center, resolution,
  * and rotation of the map.
  *
+ * A View has a `projection`. The projection determines the
+ * coordinate system of the center, and its units determine the units of the
+ * resolution (projection units per pixel). The default projection is
+ * Spherical Mercator (EPSG:3857).
+ *
  * ### The view states
  *
  * An View is determined by three states: `center`, `resolution`,
@@ -202,11 +207,6 @@ const DEFAULT_MIN_ZOOM = 0;
  * methods are available, as well as `getResolutionForZoom` and
  * `getZoomForResolution` to switch from one system to the other.
  *
- * A View has a `projection`. The projection determines the
- * coordinate system of the center, and its units determine the units of the
- * resolution (projection units per pixel). The default projection is
- * Spherical Mercator (EPSG:3857).
- *
  * ### The constraints
  *
  * `setCenter`, `setResolution` and `setRotation` can be used to change the
@@ -218,7 +218,7 @@ const DEFAULT_MIN_ZOOM = 0;
  *
  * The *resolution constraint* typically restricts min/max values and
  * snaps to specific resolutions. It is determined by the following
- * options: `resolutions`, `maxResolution`, `maxZoom`, and `zoomFactor`.
+ * options: `resolutions`, `maxResolution`, `maxZoom` and `zoomFactor`.
  * If `resolutions` is set, the other three options are ignored. See
  * documentation for each option for more information. By default, the view
  * only has a min/max restriction and allow intermediary zoom levels when
@@ -226,7 +226,7 @@ const DEFAULT_MIN_ZOOM = 0;
  *
  * The *rotation constraint* snaps to specific angles. It is determined
  * by the following options: `enableRotation` and `constrainRotation`.
- * By default the rotation value is snapped to zero when approaching the
+ * By default rotation is allowed and its value is snapped to zero when approaching the
  * horizontal.
  *
  * The *center constraint* is determined by the `extent` option. By

src/ol/renderer/webgl/PointsLayer.js

@@ -114,6 +114,7 @@ const FRAGMENT_SHADER = `
  *
  * Points are rendered as quads with the following structure:
  *
+ * ```
  *   (u0, v1)      (u1, v1)
  *  [3]----------[2]
  *   |`           |
@@ -124,6 +125,7 @@ const FRAGMENT_SHADER = `
  *   |          ` |
  *  [0]----------[1]
  *   (u0, v0)      (u1, v0)
+ *  ```
  *
  * This uses {@link module:ol/webgl/Helper~WebGLHelper} internally.
  *

src/ol/webgl.js

@@ -58,36 +58,50 @@ export const ONE_MINUS_SRC_ALPHA = 0x0303;
 
 
 /**
+ * Used by {@link module:ol/webgl/Helper~WebGLHelper} for buffers containing vertices data, such as
+ * position, color, texture coordinate, etc. These vertices are then referenced by an index buffer
+ * to be drawn on screen (see {@link module:ol/webgl.ELEMENT_ARRAY_BUFFER}).
  * @const
  * @type {number}
+ * @api
  */
 export const ARRAY_BUFFER = 0x8892;
 
 
 /**
+ * Used by {@link module:ol/webgl/Helper~WebGLHelper} for buffers containing indices data.
+ * Index buffers are essentially lists of references to vertices defined in a vertex buffer
+ * (see {@link module:ol/webgl.ARRAY_BUFFER}), and define the primitives (triangles) to be drawn.
  * @const
  * @type {number}
+ * @api
  */
 export const ELEMENT_ARRAY_BUFFER = 0x8893;
 
 
 /**
+ * Used by {link module:ol/webgl/Buffer~WebGLArrayBuffer}.
  * @const
  * @type {number}
+ * @api
  */
 export const STREAM_DRAW = 0x88E0;
 
 
 /**
+ * Used by {link module:ol/webgl/Buffer~WebGLArrayBuffer}.
  * @const
  * @type {number}
+ * @api
  */
 export const STATIC_DRAW = 0x88E4;
 
 
 /**
+ * Used by {link module:ol/webgl/Buffer~WebGLArrayBuffer}.
  * @const
  * @type {number}
+ * @api
  */
 export const DYNAMIC_DRAW = 0x88E8;
 

src/ol/webgl/Buffer.js

@@ -4,20 +4,27 @@
 import {STATIC_DRAW, STREAM_DRAW, DYNAMIC_DRAW} from '../webgl.js';
 
 /**
+ * Used to describe the intended usage for the data: `STATIC_DRAW`, `STREAM_DRAW`
+ * or `DYNAMIC_DRAW`.
  * @enum {number}
  */
-const BufferUsage = {
+export const BufferUsage = {
   STATIC_DRAW: STATIC_DRAW,
   STREAM_DRAW: STREAM_DRAW,
   DYNAMIC_DRAW: DYNAMIC_DRAW
 };
 
-
+/**
+ * @classdesc
+ * Object used to store an array of data as well as usage information for that data.
+ * See the documentation of [WebGLRenderingContext.bufferData](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/bufferData) for more info.
+ * @api
+ */
 class WebGLArrayBuffer {
 
   /**
    * @param {Array<number>=} opt_arr Array.
-   * @param {number=} opt_usage Usage.
+   * @param {number=} opt_usage Usage, either `STATIC_DRAW`, `STREAM_DRAW` or `DYNAMIC_DRAW`. Default is `DYNAMIC_DRAW`.
    */
   constructor(opt_arr, opt_usage) {
 

src/ol/webgl/Helper.js

@@ -28,7 +28,7 @@ import {getContext} from '../webgl';
  */
 
 /**
- * Shader types, either `FRAGMENT_SHADER` or `VERTEX_SHADER`
+ * Shader types, either `FRAGMENT_SHADER` or `VERTEX_SHADER`.
  * @enum {number}
  */
 export const ShaderType = {
@@ -37,9 +37,9 @@ export const ShaderType = {
 };
 
 /**
- * Uniform names used in the default shaders.
+ * Uniform names used in the default shaders: `PROJECTION_MATRIX`, `OFFSET_SCALE_MATRIX`.
- * @const
+ * and `OFFSET_ROTATION_MATRIX`.
- * @type {Object.<string,string>}
+ * @enum {string}
  */
 export const DefaultUniform = {
   PROJECTION_MATRIX: 'u_projectionMatrix',
@@ -48,9 +48,9 @@ export const DefaultUniform = {
 };
 
 /**
- * Attribute names used in the default shaders.
+ * Attribute names used in the default shaders: `POSITION`, `TEX_COORD`, `OPACITY`,
- * @const
+ * `ROTATE_WITH_VIEW`, `OFFSETS` and `COLOR`
- * @type {Object.<string,string>}
+ * @enum {string}
  */
 export const DefaultAttrib = {
   POSITION: 'a_position',
@@ -74,7 +74,7 @@ export const DefaultAttrib = {
 /**
  * @typedef {Object} PostProcessesOptions
  * @property {number} [scaleRatio] Scale ratio; if < 1, the post process will render to a texture smaller than
- * the main canvas that will then be sampled up (useful for saving resource on blur steps).
+ * the main canvas which will then be sampled up (useful for saving resource on blur steps).
  * @property {string} [vertexShader] Vertex shader source
  * @property {string} [fragmentShader] Fragment shader source
  * @property {Object.<string,UniformValue>} [uniforms] Uniform definitions for the post process step
@@ -82,7 +82,7 @@ export const DefaultAttrib = {
 
 /**
  * @typedef {Object} Options
- * @property {Object.<string,UniformValue>} [uniforms] Uniform definitions; property namesmust math the uniform
+ * @property {Object.<string,UniformValue>} [uniforms] Uniform definitions; property names must match the uniform
  * names in the provided or default shaders.
  * @property {Array<PostProcessesOptions>} [postProcesses] Post-processes definitions
  */
@@ -113,7 +113,7 @@ export const DefaultAttrib = {
  *
  *   * Varyings usually prefixed with `v_` are passed on to the fragment shader
  *
- *   Fragment shaders are used to control the actual color of the pixels rawn on screen. Their only output is `gl_FragColor`.
+ *   Fragment shaders are used to control the actual color of the pixels drawn on screen. Their only output is `gl_FragColor`.
  *
  *   Both shaders can take *uniforms* or *attributes* as input. Attributes are explained later. Uniforms are common, read-only values that
  *   can be changed at every frame and can be of type float, arrays of float or images.
@@ -150,16 +150,16 @@ export const DefaultAttrib = {
  *
  *   The {@link module:ol/webgl/PostProcessingPass~WebGLPostProcessingPass} class is used internally, refer to its documentation for more info.
  *
- * ### Binding WebGL buffers and flushing data into them:
+ * ### Binding WebGL buffers and flushing data into them
  *
- *   Data that must be passed to the GPU has to be transferred using `WebGLArrayBuffer` objects.
+ *   Data that must be passed to the GPU has to be transferred using {@link module:ol/webgl/Buffer~WebGLArrayBuffer} objects.
- *   A buffer has to be created only once, but must be bound everytime the buffer content should be used for rendering.
+ *   A buffer has to be created only once, but must be bound every time the buffer content will be used for rendering.
- *   This is done using `WebGLHelper.bindBuffer`.
+ *   This is done using {@link bindBuffer}.
  *   When the buffer's array content has changed, the new data has to be flushed to the GPU memory; this is done using
- *   `WebGLHelper.flushBufferData`. Note: this operation is expensive and should be done as infrequently as possible.
+ *   {@link flushBufferData}. Note: this operation is expensive and should be done as infrequently as possible.
  *
- *   When binding a `WebGLArrayBuffer`, a `target` parameter must be given: it should be either {@link module:ol/webgl~ARRAY_BUFFER}
+ *   When binding an array buffer, a `target` parameter must be given: it should be either {@link module:ol/webgl.ARRAY_BUFFER}
- *   (if the buffer contains vertices data) or {@link module:ol/webgl~ELEMENT_ARRAY_BUFFER} (if the buffer contains indices data).
+ *   (if the buffer contains vertices data) or {@link module:ol/webgl.ELEMENT_ARRAY_BUFFER} (if the buffer contains indices data).
  *
  *   Examples below:
  *   ```js
@@ -179,8 +179,8 @@ export const DefaultAttrib = {
  * ### Specifying attributes
  *
  *   The GPU only receives the data as arrays of numbers. These numbers must be handled differently depending on what it describes (position, texture coordinate...).
- *   Attributes are used to specify these uses. Use `WebGLHelper.enableAttributeArray` and either
+ *   Attributes are used to specify these uses. Use {@link enableAttributeArray} and either
- *   the default attribute names in {@link module:ol/webgl/Helper~DefaultAttrib} or custom ones.
+ *   the default attribute names in {@link module:ol/webgl/Helper.DefaultAttrib} or custom ones.
  *
  *   Please note that you will have to specify the type and offset of the attributes in the data array. You can refer to the documentation of [WebGLRenderingContext.vertexAttribPointer](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/vertexAttribPointer) for more explanation.
  *   ```js
@@ -194,7 +194,7 @@ export const DefaultAttrib = {
  *
  * ### Rendering primitives
  *
- *   Once all the steps above have been achieved, rendering primitives to the screen is done using `WebGLHelper.prepareDraw` `drawElements` and `finalizeDraw`.
+ *   Once all the steps above have been achieved, rendering primitives to the screen is done using {@link prepareDraw}, {@link drawElements} and {@link finalizeDraw}.
  *   ```js
  *   // frame preparation step
  *   this.context.prepareDraw(frameState);