Merge pull request #12 from 2gis/TILES-4788-reference-docs

Add docs reference comments

Author: Kuznecoff

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@2gis/deck2gis-layer",
-  "version": "1.1.2",
+  "version": "1.1.3",
   "description": "",
   "main": "dist/deck2gislayer.js",
   "typings": "dist/types/index.d.ts",

package.json

@@ -18,14 +18,19 @@ import Texture from '2gl/Texture';
 import type Vao from '2gl/Vao';
 import type ShaderProgram from '2gl/ShaderProgram';
 
-export type LayerProps<LayerT extends Layer> = Partial<LayerT['props']> & {
+export type DeckInternalLayerProps = {
     id: string;
     renderingMode?: '2d' | '3d';
     deck: Deck;
     type: any;
     antialiasing?: boolean;
 };
 
+export type LayerProps<LayerT extends Layer> = Partial<LayerT['props']> & DeckInternalLayerProps;
+
+/**
+ * A class that provides rendering any deck.gl layer inside the MapGl canvas / WebGL context.
+ */
 export class Deck2gisLayer<LayerT extends Layer> implements DeckCustomLayer {
     id: string;
     type: 'custom';
@@ -44,6 +49,22 @@ export class Deck2gisLayer<LayerT extends Layer> implements DeckCustomLayer {
     private vao?: Vao;
 
     /* eslint-disable no-this-before-super */
+    /**
+     * Example:
+     * ```js
+     * const deckLayer = new mapgl.Deck2gisLayer(map, {
+     *     id: 'deckLayer',
+     *     deck,
+     *     type: HexagonLayer,
+     *     data,
+     *     getPosition: (d) => [d.point.lon, d.point.lat]
+     * });
+     *
+     * map.addLayer(deckLayer);
+     * ```
+     * @param map The map instance.
+     * @param options Deck2gisLayer initialization options.
+     */
     constructor(props: LayerProps<LayerT>) {
         if (!props.id) {
             throw new Error('Layer must have a unique id');
@@ -58,6 +79,11 @@ export class Deck2gisLayer<LayerT extends Layer> implements DeckCustomLayer {
         this.antialiasing = Boolean(props.antialiasing);
     }
 
+    /**
+     * @hidden
+     * @internal
+     * MapGL calls this method after adding a layer to a map.
+     */
     public onAdd = () => {
         if (!this.map && this.props.deck) {
             const map = (this.props.deck.props as CustomRenderProps)._2gisData._2gisMap;
@@ -94,12 +120,20 @@ export class Deck2gisLayer<LayerT extends Layer> implements DeckCustomLayer {
         }
     };
 
+    /**
+     * @hidden
+     * @internal
+     * MapGL calls this method after removing a layer from a map.
+     */
     public onRemove = () => {
         if (this.deck) {
             removeLayer(this.deck, this);
         }
     };
 
+    /**
+     * Sets layer properties and updates the layer.
+     */
     public setProps(props: Partial<LayerProps<LayerT>>) {
         // id cannot be changed
         Object.assign(this.props, props, { id: this.id });
@@ -110,6 +144,11 @@ export class Deck2gisLayer<LayerT extends Layer> implements DeckCustomLayer {
         }
     }
 
+    /**
+     * @hidden
+     * @internal
+     * MapGL calls this method on each map frame rendering.
+     */
     public render = () => {
         if (
             !this.deck ||

src/deckgl2gisLayer.ts

@@ -30,11 +30,17 @@ export interface MapViewState {
     fovy: number;
 }
 
-export type CustomRenderProps = Partial<DeckProps> & {
+/**
+ * @hidden
+ * @internal
+ */
+export type CustomRenderInternalProps = {
     _2glRenderTarget: RenderTarget;
     _2glProgram: ShaderProgram;
     _2glVao: Vao;
     _2gisFramestart: boolean;
     _customRender: (reason: string) => void;
     _2gisData?: any;
 };
+
+export type CustomRenderProps = Partial<DeckProps> & CustomRenderInternalProps;

src/types.ts

@@ -197,6 +197,11 @@ function updateLayers(deck: Deck): void {
     deck.setProps({ layers });
 }
 
+/**
+ * Initializes deck.gl properties for working with the MapGL map.
+ * @param map The map instance.
+ * @param deckProps CustomRenderProps initialization options.
+ */
 export function initDeck2gisProps(map: Map, deckProps?: CustomRenderProps): DeckProps {
     const gl = map.getWebGLContext();
     const deck2gisProps: any = {

src/utils.ts

@@ -32,6 +32,10 @@ export class MapglMercatorViewport extends WebMercatorViewport {
     }
 }
 
+/**
+ * @hidden
+ * @internal
+ */
 export function getViewState(map: Map): WebMercatorViewportOptions & {
     padding: {
         left: number;