typedoc for documentation (#562)

Author: jpoehnelt

.gitignore

@@ -2,6 +2,7 @@
 **/package-lock.json
 **dist/
 **/.npmrc
+**/docs
 
 # Logs
 logs

.travis.yml

@@ -3,7 +3,19 @@ node_js:
 - stable
 script:
 - npm run ci
+- npm run docs
 - lerna exec "codecov"
+before_deploy:
+- touch docs/.nojekyll
+deploy:
+  provider: pages
+  skip_cleanup: true
+  github_token: "$GITHUB_TOKEN"
+  keep_history: true
+  committer_from_gh: true
+  local_dir: docs
+  on:
+    branch: master
 env:
   global:
-    secure: tBVMdVCrBSggJUSlAmyiwOPrRr86NQ6GRcUa4JXwGJuDqb6twf8v7pzmUTnf4FMP+VSE0bVn0QxXHkfK4adyytqGtbjbKuaShvqR02J84F80gMV2IP5Ik+Y3GmvBL/lQKIRt1Jmsqa2mhLU2/qvy9K0iKP+bPuF/vm06Rt5jYZbUGQT9qPW0P96WyZcx85hEu+V+ydVEx8RQAkD507WW4SgRNlrDmQhfA2Kxpy7xkm1z7RizeHW0yDIWzMThZpt1AL788EsNBNo/U35x6NN2xDxLP99uUpCg3B7vnzU4Xfq4wUwb77+b6qSvDlrUQOLWfRmilcZorr7kQvk2/FnFpnHhTXkYpGzUaUTe+JrrkE1sq5qqkbYPtqKmA4xwnHjG5bvrapI1A2aWuknf9ErnTSPuHTei1LWTn3Cj3CmPzXI4scvSHIlIc5Ns7KODFm2k56SFiNYvJ86SgoEg+7jwEyEtuF3/9e9WUGGDnjHIpFvgiLhV34QPKOB3skyJF8NI9ZuPYFHBr78zSUHdYyZZTLrAClPVr1JuqB9T0aG+cGrtdVEA8u1NdIjRLVX647YfpDAAEnGdbDzjHx3YrQOJAkBe5nrMqr9000BhP8B1yDuETwbVMLoBat0HxqH4UJCy6rvsNvSScX2G2fAuDVx5Jyfb9vafGTuT1nyTH2jTN14=
+    secure: fnIHhOmHE9tFYzo1pYa4d9jAELBYPCvS7Bmqpw3BH8iIJrnROEcIQa96G98RUchb1pop7tg+DxDdgMdBLxfriTRMzskbyeAhvuIgF8uL706jzlRgZHz5Jg5y933BW4hegFxbDMoSnShNwBoqH3QkFj/wHqCqOTEwd3m+ahMlGyWKvUDmEVL+K/D7j2Tq6dtFPIu1tgX3gPd9KWSEznFE1NrWSVCSSaz2j99Neq6PllI2qE7v7V4fCXFxn2Dc2TxEwuxOvfumucFQsGezd4WMJI7nPO94v7Ggt1FUgxZ/Q5qiykEQuYvXsIjW6CRTqFmNiiJLqVKCVlYNQcgCRoQtGJ0cukjG48q2NU6aw9szuVP+9hisSoJK7DLKGDw1Qozx+OtOe/wQHuXhyxbt6FJRg6JGILYpVAPfn+HyHwldqgyUHvMUZkWIV4CE1K4cclKa/u8XloJ6vOtdQRvwcgLXn7KI0r3P50NdTA0Nm9JdJgfqZL58PHBs2T8y3qHOR0FRehAqWHqnd2fPdm8WsZkS646moNaw+WA85mUr6da/uuiR1AH/tAsusL3ObDeIFRhuMOT+rXdG/Rpiibnf+9FamRPtB7HvVXSCFEoOSPEYoO23sdLqTZPD2eTS/Vxn8pKQnb9+hlINNKy3UiCcYDB3iON+KuJ5qHuMhSEkG10efZA=

README.md

@@ -1,30 +1,50 @@
 [![Build Status](https://travis-ci.org/googlemaps/v3-utility-library.svg?branch=master)](https://travis-ci.org/googlemaps/v3-utility-library)
 [![codecov](https://codecov.io/gh/googlemaps/v3-utility-library/branch/master/graph/badge.svg)](https://codecov.io/gh/googlemaps/v3-utility-library)
 ![GitHub contributors](https://img.shields.io/github/contributors/googlemaps/v3-utility-library)
+![TypeScript](https://badgen.net/badge/icon/Typed?icon=typescript&label&labelColor=blue&color=555555)
+![Apache-2.0](https://img.shields.io/badge/license-Apache-blue)
 
-Plugins for Google Maps JavaScript API v3
+Google Maps JavaScript API v3 Utilities
 ===================================================
 
 ## Description
 
-In this project you can find a set of utility libraries developed for Google Maps JavaScript API v3:
+In this project you can find a utility packages developed for the Google Maps JavaScript API V3.
 
-- ArcGIS Server Link for Google Maps JavaScript API V3
+## Documentation
+
+Documentation for the utility packages below can be found at https://googlemaps.github.io/v3-utility-library/.
+
+## Packages
+- @googlemaps/jest-mocks Jest mocks for Google Maps in TypeScript
+- @googlemaps/loader - Dynamic loader for Google Maps script using Promise or callback patterns
+- @googlemaps/ogc - WMS Layers and more(tbd)
+- @google/markerclusterer - Cluster nearby markers
+- @google/markerclustererplus - Extended version of @google/markerclusterer
+- @googlemaps/markermanager - Show and hide markers based on zoom and bounds to improve performance
+- @google/markerwithlabel - Markers with labels and matching events
+
+## Archive
+
+The following packages have never been officially published and are not maintained. Please open an issue to prioritize their inclusion.
+- ArcGIS Server Link
 - CanvasLayer
-- ExtOverviewMapControl for V3
-- Geolocation Marker for Google Maps v3
+- ExtOverviewMapControl
+- Geolocation Marker
 - InfoBox
 - InfoBubble
-- KeyDragZoom for V3
-- MapLabel for Google Maps V3
-- MarkerClusterer for Google Maps v3
-- MarkerClustererPlus for Google Maps V3
-- MarkerManager v3
-- MarkerWithLabel for V3
-- RichMarker for Google Maps v3
+- KeyDragZoom
+- MapLabel
+- RichMarker
 - RouteBoxer
 - StyledMarker
 
+## Other Resources
+- [Google Maps VS Documentation](https://developers.google.com/maps/documentation/javascript/tutorial)
+- [Google Maps V3 Reference Documenations](https://developers.google.com/maps/documentation/javascript/reference/)
+- [Google Maps Typings](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/googlemaps) - Community supported `npm i -D @types/googlemaps`
+- [Google Maps V3 Samples](https://github.com/googlemaps/js-samples)
+
 ## Support
 
 These libraries are community supported. We're comfortable enough with the stability and features of

archive/README.md

@@ -1,3 +1,3 @@
 # Archived
 
-The packages in this folder have been moved here because they have never been published. To open prioritize one of these packages for update and publishing to npm, please open an issue.
+The packages in this folder have been moved here because they have never been published and are not maintained. To open prioritize one of these packages for update and publishing to npm, please open an issue.

package.json

@@ -3,7 +3,8 @@
   "private": true,
   "scripts": {
     "bootstrap": "lerna bootstrap",
-    "ci": "npm run bootstrap && npm run prepare && npm run lint && npm run test",
+    "ci": "npm run lint && npm run test",
+    "docs": "rm -rf docs/ && typedoc .",
     "format": "sort-package-json && prettier *.json *.js --write && lerna run format",
     "lint": "lerna run lint",
     "prepare": "lerna run prepare",
@@ -15,9 +16,11 @@
     "@google/markerwithlabel": "file:packages/markerwithlabel",
     "@googlemaps/jest-mocks": "file:packages/jest-mocks",
     "@googlemaps/loader": "file:packages/loader",
+    "@googlemaps/markermanager": "file:packages/markermanager",
     "@googlemaps/ogc": "file:packages/ogc"
   },
   "devDependencies": {
+    "@googlemaps/jest-mocks": "file:../jest-mocks",
     "@types/googlemaps": "^3.37.7",
     "@types/jest": "^24.0.19",
     "@typescript-eslint/eslint-plugin": "^2.4.0",
@@ -31,13 +34,16 @@
     "jest": "^24.9.0",
     "lerna": "^3.16.4",
     "prettier": "^1.18.2",
+    "query-string": "^6.8.3",
     "rollup": "^1.24.0",
     "rollup-plugin-commonjs": "^10.1.0",
     "rollup-plugin-node-resolve": "^5.2.0",
     "rollup-plugin-terser": "^5.1.2",
     "rollup-plugin-typescript2": "^0.24.3",
     "sort-package-json": "^1.22.1",
     "ts-jest": "^24.1.0",
+    "typedoc": "^0.15.0",
+    "typedoc-plugin-lerna-packages": "^0.2.1",
     "typescript": "^3.6.4"
   }
 }

packages/jest-mocks/CONTRIB.md

@@ -0,0 +1,24 @@
+How to contribute
+=================
+
+Want to help out? That's awesome!
+
+The library is open source and lives on GitHub at:
+https://github.com/googlemaps/v3-utility-library/tree/master/packages/jest-mocks.
+Open an issue or fork the library and submit a pull request.
+
+Keep in mind that before we can accept any pull requests we have to jump
+through a couple of legal hurdles, primarily a Contributor License Agreement
+(CLA):
+
+- **If you are an individual writing original source code**
+  and you're sure you own the intellectual property,
+  then you'll need to sign an
+  [individual CLA](http://code.google.com/legal/individual-cla-v1.0.html).
+- **If you work for a company that wants to allow you to contribute your work**,
+  then you'll need to sign a
+  [corporate CLA](http://code.google.com/legal/corporate-cla-v1.0.html)
+
+Follow either of the two links above to access the appropriate CLA and
+instructions for how to sign and return it. Once we receive it, we'll be able
+to accept your pull requests.

packages/jest-mocks/README.md

@@ -0,0 +1,33 @@
+Jest Mocks for Google Maps v3
+=============================
+
+## Description
+
+Jest mocks for Google Maps in TypeScript. 
+
+**Note:** Currently this is a partial set of mocks/stubs.
+
+## NPM
+
+Available via NPM as the package `@googlemaps/jest-mocks`
+
+## Example
+
+```typescript
+import { initialize } from "@googlemaps/jest-mocks";
+
+beforeEach(() => {
+  initialize();
+});
+
+```
+
+## Support
+
+This library is community supported. We're comfortable enough with the stability and features of
+the library that we want you to build real production applications on it.
+
+If you find a bug, or have a feature suggestion, please [log an issue][issues]. If you'd like to
+contribute, please read [How to Contribute][contrib].
+
+[issues]: https://github.com/googlemaps/v3-utility-library/issues

packages/markermanager/README.md

@@ -5,7 +5,7 @@ MarkerManager v3
 
 Marker manager is an interface between the map and the user, designed to manage adding and removing many points when the viewport changes. 
 
-###How it Works:
+### How it Works:
 
 The MarkerManager places its markers onto a grid, similar to the map tiles. When the user moves the viewport, it computes which grid cells have entered or left the viewport, and shows or hides all the markers in those cells. (If the users scrolls the viewport beyond the markers that are loaded, no markers will be visible until the EVENT_moveend triggers an update.) In practical consequences, this allows 10,000 markers to be distributed over a large area, and as long as only 100-200 are visible in any given viewport, the user will see good performance corresponding to the 100 visible markers, rather than poor performance corresponding to the total 10,000 markers. Note that some code is optimized for speed over space, with the goal of accommodating thousands of markers.
 

packages/markermanager/src/gridbounds.ts

@@ -16,8 +16,7 @@
 
 /**
  * Helper class to create a bounds of INT ranges.
- * @param bounds Array.<Object.<string, number>> Bounds object.
- * @constructor
+ * @ignore
  */
 export class GridBounds {
   public z: number;
@@ -26,6 +25,11 @@ export class GridBounds {
   public minY: number;
   public maxY: number;
 
+  /**
+   *
+   * @param bounds
+   * @param z
+   */
   constructor(bounds: google.maps.Point[], z: number) {
     // [sw, ne]
     this.z = z;

packages/markermanager/src/markermanager.ts

@@ -25,21 +25,9 @@ interface Options {
   trackMarkers?: boolean;
   borderPadding?: number;
 }
+
 /**
  * Creates a new MarkerManager that will show/hide markers on a map.
- *
- * Events:
- * @event changed (Parameters: shown bounds, shown markers) Notify listeners when the state of what is displayed changes.
- * @event loaded MarkerManager has succesfully been initialized.
- *
- * @constructor
- * @param map The map to manage.
- * @param options A container for optional arguments:
- *   maxZoom The maximum zoom level for which to create tiles.
- *   borderPadding The width in pixels beyond the map border,
- *                   where markers should be display.
- *   trackMarkers Whether or not this manager should track marker
- *                   movements.
  */
 class MarkerManager {
   public shown: boolean;
@@ -57,6 +45,11 @@ class MarkerManager {
   private _numMarkers: { [k: string]: number };
   private _shownBounds: GridBounds;
 
+  /**
+   * @constructor
+   * @param map The map to manage.
+   * @param {Options} options
+   */
   constructor(
     map: google.maps.Map,
     { maxZoom = 19, trackMarkers, shown = true, borderPadding = 100 }: Options

packages/markermanager/src/utils.ts

@@ -14,15 +14,31 @@
  * limitations under the License.
  */
 
+/**
+ * @ignore
+ *
+ * @param lng
+ */
 function lngToX(lng: number): number {
   return 1 + lng / 180;
 }
-
+/**
+ * @ignore
+ *
+ * @param {number} lat
+ * @returns {number}
+ */
 function latToY(lat: number): number {
   const sinofphi = Math.sin((lat * Math.PI) / 180);
   return 1 - (0.5 / Math.PI) * Math.log((1 + sinofphi) / (1 - sinofphi));
 }
 
+/**
+ * @ignore
+ *
+ * @param latlng
+ * @param zoom
+ */
 export function latLngToPixel(
   latlng: google.maps.LatLng,
   zoom: number

packages/ogc/src/index.ts

@@ -14,4 +14,4 @@
  * limitations under the License.
  */
 
-export { WMSLayer } from "./wmslayer";
+export { WMSLayer, WMSLayerOptions, xyzToBounds } from "./wmslayer";

packages/ogc/src/wmslayer.ts

@@ -17,16 +17,39 @@
 /// <reference types="@types/googlemaps" />
 import { stringify } from "query-string";
 
+/**
+ * @ignore
+ */
 const DEFAULT_WMS_PARAMS = {
   request: "GetMap",
   service: "WMS",
   srs: "EPSG:3857"
 };
+
+/**
+ * @ignore
+ */
 const EPSG_3857_EXTENT = 20037508.34789244;
+
+/**
+ * @ignore
+ */
 const ORIG_X = -EPSG_3857_EXTENT; // x starts from right
+
+/**
+ * @ignore
+ */
 const ORIG_Y = EPSG_3857_EXTENT; // y starts from top
 
-function xyzToBounds(x: number, y: number, zoom: number): Array<number> {
+/**
+ * Convert xyz tile coordinates to mercator bounds.
+ *
+ * @param x
+ * @param y
+ * @param zoom
+ * @returns {number[]} minx, miny, maxx, maxy
+ */
+function xyzToBounds(x: number, y: number, zoom: number): number[] {
   const tileSize = (EPSG_3857_EXTENT * 2) / Math.pow(2, zoom);
   const minx = ORIG_X + x * tileSize;
   const maxx = ORIG_X + (x + 1) * tileSize;
@@ -50,6 +73,11 @@ interface WMSLayerOptions {
   minZoom?: number;
   opacity?: number;
 }
+
+/**
+ *
+ * @param {WMSLayerOptions} params
+ */
 const WMSLayer = function({
   url,
   layers,

typedoc.js

@@ -0,0 +1,14 @@
+module.exports = {
+  mode: "modules",
+  target: "es6",
+  out: "docs",
+  exclude: ["**/node_modules/**", "**/*.spec.ts", "**/*.test.ts"],
+  lernaExclude: [],
+  name: "Google Maps JavaScript API v3 Utilities",
+  excludePrivate: true,
+  skipInternal: true,
+  ignoreCompilerErrors: true,
+  module: "commonjs",
+  categorizeByGroup: true,
+  readme: "./README.md"
+};