Migrate JSDocs to TSDocs (#2756)

* Some examples of conversion * More experiments * Fix group name * Fix lint * made basic UI changes (#2755) * Move more comments to their right place * Remove more tsdocs comments * Fix lint, complete map jsdocs removal * Fix lint, remove return types from jsdocs comments. * Js ts controls (#2777) * Fix some controls * Replace jsdoc with tsdocs lint * Fix control's jsdocs * Improve the looks of the controls * Fix lint and CI * Remove the last jsdoc comments in geolocation control * Introduce max canvas size option and automatically limit pixel ratio (#2674) * rendering test: implement cropping of png result This is useful for renderer results that are too large to be handled by puppeteer * mock webgl: update drawing buffer size when viewport changes * Round down painter and canvas dimensions so they're consistent * add veryhigh pixel ratio test This test draws a black square, The pixel ratio and width were chosen to exceed the maximum texture value, which is set to 8192 in the CI environment. The result is cropped due to the limits of the intercommunication between chromium and puppeteer. * introduce maxCanvasSize option A canvas size over GL MAX_TEXTURE_SIZE can cause distortions and an excessive canvas size can cause hangs or crashes. Limiting canvas size can fix these issues. Add an option to let the users alter this limit. The default value is [4096, 4096] as MAX_TEXTURE_SIZE is usally at least 4096px. In CI max_texture_size is 8192, so we set maxCanvasSize to that value in tests. * Resize map after setting pixel ratio This has two benefits: 1. The map is immediately re-rendered with the new pixel ratio 2. We avoid duplicating pixel ratio clamping logic * further clamp pixel ratio after hitting gl limits Althoug setting maxCanvasSize to a value <= GL.MAX_TEXTURE_SIZE solves most problems, there is no guarantee that we cannot exceed other GL limits. To handle these cases, we check that the drawing buffer is of the requested size, if it isn't we scale down pixel ratio further * map test: move webgl error in its own section * add a unit test for webgl drawing buffer limits * update maxCanvasSize type and change comment type * update maxCanvasSize after hitting gl limits This is an optimization to avoid failing the overlimit check multiple times. * update changelog * Added handlers to the docs (#2778) * Added handlers to the docs * Fix lint * Small changes to the docs contribution guide (#2791) * Changes to docs contribution * don't link for better review * Migrated popup and marker (#2790) * Migrated marker and popup * Fix lint * Code review fixes * Added missing marker options object * Fix lint and tests * Fix typo * remove unneeded lint comment. * Bump typescript from 5.1.5 to 5.1.6 (#2787) Bumps [typescript](https://github.com/Microsoft/TypeScript) from 5.1.5 to 5.1.6. - [Release notes](https://github.com/Microsoft/TypeScript/releases) - [Commits](https://github.com/Microsoft/TypeScript/commits) --- updated-dependencies: - dependency-name: typescript dependency-type: direct:development update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * Fix sources (#2795) * Fix sources * Added typedoc * Fix custom style layer * Fix test, add comments * fix grammer spelling * More minor fixes * JSDocs TSDocs leftovers (#2801) * insets, lnglat+bounds * mercator * transform * draw_terrain * line_atlas * terrain * tile, styel_image * actore * ajax * image request queue * struct array * Remove returns objects * typedef * remove function * Removed some prperties * Fix lint * Fix tests * Lint, cr fixes * TSDocs JSDocs migration: build warning removal (#2802) * Added comments to reduce warnings * Fix most of the warnings in the build process * TSDocs lint (#2804) * Move all examples to be tripple slash, hypen, remove @Private * delimiter fix * More fixes * Fix lint * Remove unneeded rule * Code review changes. * Fix var let bad replacenment * Fix typo * Fix bwc address * Small fixes to the event related docs * Fix lint * Fix the event related issue * Added Geography and Geometry group (#2808) * Added Geography and Geometry * Fix lint * Finished the event documentation * Fix lint * Main docs readme links fixes and CI (#2813) * Fix main readme links * make links relative * More readme fixes * Adding build to CI * Simplify docker commend * Change site url in the config to match the expected production site. * Added CI part * Final small fixes. --------- Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: Krishna Lodha <[email protected]> Co-authored-by: Andrea Mennillo <[email protected]> Co-authored-by: Birk Skyum <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
maplibre · Jul 8, 2023 · f329d91 · f329d91
1 parent 3c23fe5
commit f329d91
Show file tree

Hide file tree

Showing 150 changed files with 4,255 additions and 6,527 deletions.
diff --git a/.eslintrc b/.eslintrc
@@ -13,7 +13,7 @@
   "plugins": [
     "@typescript-eslint",
     "import",
-    "jsdoc",
+    "eslint-plugin-tsdoc",
     "jest"
   ],
   "rules": {
@@ -80,15 +80,7 @@
         "max": 1
     }],
     "import/no-relative-packages": ["error"],
-    "jsdoc/check-param-names": "warn",
-    "jsdoc/require-param": "warn",
-    "jsdoc/require-param-description": "warn",
-    "jsdoc/require-param-name": "warn",
-    "jsdoc/require-returns": "warn",
-    "jsdoc/require-returns-description": "warn",
-    "jsdoc/check-alignment": "error",
-    "jsdoc/check-line-alignment": "error",
-
+    "tsdoc/syntax": "warn",
     // Jest https://www.npmjs.com/package/eslint-plugin-jest
     "jest/no-commented-out-tests": "error",
     "jest/no-disabled-tests": "warn",
@@ -103,25 +95,7 @@
     "jest/no-deprecated-functions": "warn"
   },
   "reportUnusedDisableDirectives": true,
-  "settings": {
-    "jsdoc":{
-      "ignorePrivate": true
-    }
-  },
   "ignorePatterns": ["build/*.js", "*.json"],
-  "overrides": [
-    {
-      "files": ["test/**"],
-      "rules": {
-        "jsdoc/check-param-names": "off",
-        "jsdoc/require-param": "off",
-        "jsdoc/require-param-description": "off",
-        "jsdoc/require-param-name": "off",
-        "jsdoc/require-returns": "off",
-        "jsdoc/require-returns-description": "off"
-      }
-    }
-  ],
   "globals": {
     "performance": true
   },

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -121,6 +121,19 @@ jobs:
           destination_dir: benchmarks/${{ steps.prepare_release.outputs.version_tag }}
           commit_message: 'deploy: ${{ steps.prepare_release.outputs.version_tag }}'
 
+      - name: Build the Docs
+        run: |
+          npm run generate-docs
+          docker run --rm -v ${PWD}:/docs squidfunk/mkdocs-material build
+
+      - name: Publish the docs
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: site
+          destination_dir: docs
+          commit_message: 'deploy docs: ${{ steps.prepare_release.outputs.version_tag }}'
+
       - name: Clean up
         if: ${{ steps.prepare_release.outputs.release_type == 'regular' }}
         run: |

diff --git a/.github/workflows/test-all.yml b/.github/workflows/test-all.yml
@@ -25,12 +25,12 @@ jobs:
         if: success() || failure()
       - run: npm run lint-css
         if: success() || failure()
-      - run: npm run lint-docs
-        if: success() || failure()
       - run: npm run generate-typings
         if: success() || failure()
       - run: npm run typecheck
         if: success() || failure()
+      - run: npm run generate-docs
+      - run: docker run --rm -v ${PWD}:/docs squidfunk/mkdocs-material build
 
   unit-tests:
     name: Unit tests and Coverage

diff --git a/.gitignore b/.gitignore
@@ -4,7 +4,7 @@
 /dist_type/
 /test/bench/results/
 /docs/API
-/docs/examples
+/docs/example
 *.es.js
 *.js.map
 node_modules

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -8,6 +8,8 @@
 - Immediately redraw the map after setting pixel ratio ([#2674](https://github.com/maplibre/maplibre-gl-js/pull/2673))
 - Add maxCanvasSize option to limit canvas size. It can prevent reaching the GL limits and reduce the load on the devices. Default value is [4096, 4096].
 - Reduce maxCanvasSize when hitting GL limits to avoid distortions ([#2674](https://github.com/maplibre/maplibre-gl-js/pull/2673))
+- Rewrite all the code comments in TSDocs, introduced a new documentaiton system and moved examples into this repository for better debug options ([#2756](https://github.com/maplibre/maplibre-gl-js/pull/2756))
+- ⚠️ Removed non documented `Marker` constructor parameter ([#2756](https://github.com/maplibre/maplibre-gl-js/pull/2756))
 - _...Add new stuff here..._
 
 ### 🐞 Bug fixes

diff --git a/build/generate-docs.ts b/build/generate-docs.ts
@@ -13,8 +13,10 @@ function generateAPIIntroMarkdown(lines: string[]): string {
     let intro = `# Intro
 
 This file is intended as a reference for the important and public classes of this API.
+We reccomend looking at the [expamples](../example/index.md) as they will help you the most to start with MapLibre.
+
+Most of the classes wirtten here have an "Options" object for initialization, it is recommended to check which options exist. 
 
-We reccomend to look at the [expamples](../examples/index.md) as they will help you the most to start with MapLibre.
 `;
     intro += lines.map(l => l.replace('../', './')).join('\n');
     return intro;
@@ -64,7 +66,7 @@ const contentString = generateAPIIntroMarkdown(lines);
 fs.writeFileSync(path.join(typedocConfig.out, 'README.md'), contentString);
 
 // Examples manupilation
-const examplesDocsFolder = path.join('docs', 'examples');
+const examplesDocsFolder = path.join('docs', 'example');
 if (fs.existsSync(examplesDocsFolder)) {
     fs.rmSync(examplesDocsFolder, {recursive: true, force: true});
 }

diff --git a/build/generate-struct-arrays.ts b/build/generate-struct-arrays.ts
@@ -236,7 +236,6 @@ function emitStructArrayLayout(locals) {
 
     output.push(
         ` *
- * @private
  */
 class ${structArrayLayoutClass} extends StructArray {`);
 
@@ -349,7 +348,8 @@ function emitStructArray(locals) {
 
     if (includeStructAccessors && !useComponentGetters) {
         output.push(
-            `class ${structTypeClass} extends Struct {
+            `/** */
+class ${structTypeClass} extends Struct {
     _structArray: ${structArrayClass};`);
 
         for (const {name, member, component} of components) {
@@ -384,9 +384,7 @@ export type ${structTypeClass.replace('Struct', '')} = ${structTypeClass};
     } // end 'if (includeStructAccessors)'
 
     output.push(
-        `/**
- * @private
- */
+        `/** */
 export class ${structArrayClass} extends ${structArrayLayoutClass} {`);
 
     if (useComponentGetters) {
@@ -407,8 +405,7 @@ export class ${structArrayClass} extends ${structArrayLayoutClass} {`);
         output.push(
             `    /**
      * Return the ${structTypeClass} at the given location in the array.
-     * @param {number} index The index of the element.
-     * @private
+     * @param index The index of the element.
      */
     get(index: number): ${structTypeClass} {
         return new ${structTypeClass}(this, index);

diff --git a/docs/README.md b/docs/README.md
@@ -1,11 +1,11 @@
 # Introduction
 
-MapLibre GL JS is a TypeScript library that uses WebGL2 to render interactive maps from vector tiles in a browser. The customization of the map comply with the [MapLibre Style Spec](https://maplibre.org/maplibre-style-spec). It is part of the [MapLibre ecosystem](https://github.com/maplibre), with a pendant for Mobile, Desktop, Servers called [MapLibre Native](https://maplibre.org/projects/maplibre-native/).
+MapLibre GL JS is a TypeScript library that uses WebGL to render interactive maps from vector tiles in a browser. The customization of the map comply with the [MapLibre Style Spec](https://maplibre.org/maplibre-style-spec). It is part of the [MapLibre ecosystem](https://github.com/maplibre), with a pendant for Mobile, Desktop, Servers called [MapLibre Native](https://maplibre.org/projects/maplibre-native/).
 
 
 ## Quickstart
 
-<iframe src="./examples/simple-map.html" width="100%" style="border:none"></iframe>
+<iframe src="./example/simple-map.html" width="100%" style="border:none"></iframe>
 
 ```html
 <div id="map"></div>
@@ -24,17 +24,18 @@ MapLibre GL JS is a TypeScript library that uses WebGL2 to render interactive ma
 
 This documentation is divided into several sections:
 
-* [**Map**](https://maplibre.org/maplibre-gl-js-docs/api/map/). The `Map` object is the map on your page. It lets you access methods and properties for interacting with the map's style and layers, respond to events, and manipulate the user's perspective with the camera.
-* [**Properties and options**](https://maplibre.org/maplibre-gl-js-docs/api/properties/). This section describes MapLibre GL JS's global properties and options that you might want to access while initializing your map or accessing information about its status.
-* [**Markers and controls**](https://maplibre.org/maplibre-gl-js-docs/api/markers/). This section describes the user interface elements that you can add to your map. The items in this section exist outside of the map's `canvas` element.
-* [**Geography and geometry**](https://maplibre.org/maplibre-gl-js-docs/api/geography/). This section includes general utilities and types that relate to working with and manipulating geographic information or geometries.
-* [**User interaction handlers**](https://maplibre.org/maplibre-gl-js-docs/api/handlers/). The items in this section relate to the ways in which the map responds to user input.
-* [**Sources**](https://maplibre.org/maplibre-gl-js-docs/api/sources/). This section describes the source types MapLibre GL JS can handle besides the ones described in the [MapLibre Style Specification](https://maplibre.org/maplibre-style-spec/).
-* [**Events**](https://maplibre.org/maplibre-gl-js-docs/api/events/). This section describes the different types of events that MapLibre GL JS can raise.
+* [**Main**](./API/#main) - The Main section holds the following classes
+    * [`Map`](./API/classes/maplibregl.Map/) object is the map on your page. It lets you access methods and properties for interacting with the map's style and layers, respond to events, and manipulate the user's perspective with the camera.
+    * [`MaplibreGL`](./API/classes/default/) object is MapLibre GL JS's global properties and options that you might want to access while initializing your map or accessing information about its status.
+* [**Markers and Controls**](./API//#markers-and-controls) - This section describes the user interface elements that you can add to your map. The items in this section exist outside of the map's `canvas` element. This consists of `Marker`, `Popup` and all the controls.
+* [**Geography and geometry**](./API/#geography-and-geometry) - This section includes general utilities and types that relate to working with and manipulating geographic information or geometries.
+* [**User interaction handlers**](./API/#handlers) - The items in this section relate to the ways in which the map responds to user input.
+* [**Sources**](./API/#sources) - This section describes the source types MapLibre GL JS can handle besides the ones described in the [MapLibre Style Specification](https://maplibre.org/maplibre-style-spec/).
+* [**Event Related**](./API/#event-related) - This section describes the different types of events that MapLibre GL JS can raise.
 
 Each section describes classes or objects as well as their **properties**, **parameters**, **instance members**, and associated **events**. Many sections also include inline code examples and related resources.
 
-In the examples, we use vector tiles from [MapTiler](https://maptiler.com). Get your own API key if you want to use MapTiler data in your project.
+In the examples, we use vector tiles our [Demo tiles repository](https://github.com/maplibre/demotiles) and from [MapTiler](https://maptiler.com). Get your own API key if you want to use MapTiler data in your project.
 
 ## CSP Directives
 
@@ -70,15 +71,14 @@ Including it with a `<link>` in the head of the document via the UNPKG CDN is th
 
 Note too that if the CSS isn't available by the first render, as soon as the CSS is provided, the DOM elements that depend on this CSS should recover.
 
-## Dependencies
+## CDN
 
-The dependencies for MapLibre GL JS (`.js` & `.css`) are distributed via [UNPKG.com](https://unpkg.com).  UNPKG can distribute a fixed version, a [semver range](https://semver.org/), a tag, or omit the version/tag entirely to use the `latest` tag.
-
-You can view a listing of all the files in the MapLibre GL JS package by appending a `/` at the end of the MapLibre slug.  This is useful to review other revisions or to review the files at UNPKG or the LICENSE.  See <https://unpkg.com/maplibre-gl/>
+The MapLibre GL JS (`.js` & `.css`) are distributed via [UNPKG.com](https://unpkg.com).
+You can view a listing of all the files in the MapLibre GL JS package by appending a `/` at the end of the MapLibre slug. This is useful to review other revisions or to review the files at UNPKG or the LICENSE. See examples in the following table:
 
 *Examples*
 
 | Use Case  | `.js` | `.css` |
 | :------- | :---: | :----: |
-| `latest` |`https://unpkg.com/maplibre-gl/dist/maplibre-gl.js` | `https://unpkg.com/maplibre-gl/dist/maplibre-gl.css` |
+| `latest` | <https://unpkg.com/maplibre-gl/dist/maplibre-gl.js> | <https://unpkg.com/maplibre-gl/dist/maplibre-gl.css> |
 | Use at least `2.4.x` | <https://unpkg.com/maplibre-gl@^2.4/dist/maplibre-gl.js> | <https://unpkg.com/maplibre-gl@^2.4/dist/maplibre-gl.css> |
diff --git a/documents_and_diagrams/README.md b/documents_and_diagrams/README.md
@@ -4,16 +4,18 @@ This folder contains developer documentation for MapLibre GL JS. Put any diagram
 
 API documentation is written as [TSDoc comments](https://tsdoc.org/) and processed with [typedoc](https://typedoc.org/)
 
-* Classes, methods, events, and anything else in the public interface must be documented with TSDoc comments. Everything outside of the public interface may be documented and must be tagged as `@private`.
+* Classes, methods, events, and anything else in the public interface must be documented with TSDoc comments, and the typescript `public` can be used to indicate that it's public API.
+* The `@internal` tag can be used to indicate that a class, method, or event is not part of the public interface and should not be documented.
+* Methods implementing an interface need an `{@inheritDoc reference}` in order to inherit the documentation from the interface.
 * Use `@group` to indicate to which group to send a specific class, these groups are defined in `typedoc.json` file and are important for the API documentation intro file.
 * Text within TSDoc comments may use markdown formatting. Code identifiers must be surrounded by \`backticks\`.
 * Documentation must be written in grammatically correct sentences ending with periods.
 * Documentation must specify measurement units when applicable.
 * Documentation descriptions must contain more information than what is obvious from the identifier and JSDoc metadata.
 * Class descriptions should describe what the class *is*, or what its instances *are*. They do not document the constructor, but the class. They should begin with either a complete sentence or a phrase that would complete a sentence beginning with "A `T` is..." or "The `T` class is..." Examples: "Lists are ordered indexed dense collections." "A class used for asynchronous computations."
 * Function descriptions should begin with a third person singular present tense verb, as if completing a sentence beginning with "This function..." If the primary purpose of the function is to return a value, the description should begin with "Returns..." Examples: "Returns the layer with the specified id." "Sets the map's center point."
-* `@param`, `@property`, and `@returns` descriptions should be capitalized and end with a period. They should begin as if completing a sentence beginning with "This is..." or "This..."
-* Functions that do not return a value (return `undefined`), should not have a `@returns` annotation.
+* `@param`, and `@returns` descriptions should be capitalized and end with a period. They should begin as if completing a sentence beginning with "This is..." or "This..."
+* Functions that do not return a value (return `void`), should not have a `@returns` annotation.
 * Member descriptions should document what a member represents or gets and sets. They should also indicate whether the member is read-only.
 * Event descriptions should begin with "Fired when..." and so should describe when the event fires. Event entries should clearly document any data passed to the handler, with a link to MDN documentation of native Event objects when applicable.
 
@@ -25,11 +27,11 @@ Examples are written as regular html files in `test/examples`. Each example shou
 
 Every example **must** have an accompanying image.
 
-1. Run `npm run generate-image <example-file-name>`. The script will take a screenshot of the map in the example and save it to `docs/assests/examples/`. Commit the image.
+1. Run `npm run generate-images <example-file-name>`. The script will take a screenshot of the map in the example and save it to `docs/assests/examples/`. Commit the image.
 
-For some examples, `npm run generate-image` does not generate an ideal image. In these cases, you can interact with the map after running the command before the screenshot is taken, or take a screenshot yourself by running the site locally with `npm start`, take a screenshot and save it in the `docs/assests/examples/` folder.
+For some examples, `npm run generate-images` does not generate an ideal image. In these cases, you can interact with the map after running the command before the screenshot is taken, or take a screenshot yourself by running the site locally with `npm start`, take a screenshot and save it in the `docs/assests/examples/` folder.
 
-To regenerate all images, run `npm run generate-image`. Note that this doesn't support interaction and examples that require manual interaction (e.g. popups) will need to be manually redone afterward. This feature is experimental and may crash before sucessfully generating all examples.
+To regenerate all images, run `npm run generate-images`. Note that this doesn't support interaction and examples that require manual interaction (e.g. popups) will need to be manually redone afterward. This feature is experimental and may crash before sucessfully generating all examples.
 
 ## Running the Documentation Server Locally
 
@@ -45,18 +47,18 @@ The examples section of the locally run documentation will use the GL JS version
 
 ## Committing and Publishing Documentation
 
-When a new GL JS release goes out the documentation will be released with it.
+When a new MapLibre GL JS release goes out the documentation will be released with it.
 
 To update or add a new example, PR the relevant changes to this repo. The example will be live once a new version will be released. If this example uses a version of GL JS that isn't yet released, the PR should not be merged until the release is out.
 
 ## How does all this work?
 
 It uses 3 tools:
-1. typedoc cli
-2. mkdocs material
+1. [TypeDoc](https://typedoc.org/) cli
+2. [MkDocs material](https://squidfunk.github.io/mkdocs-material/)
 3. `generate-docs.ts` script
 
-The typedoc cli is used to generate markdown files of the API from the TSDocs comments and places the output in API folder of the docs.
+The TypeDoc CLI convert is used to generate markdown files of the API from the TSDoc comments and places the output in API folder of the docs.
 The `generate-docs.ts` does some manipulation of this API output and also uses the examples html files from the test folder to generate markdown of the examples index file and all the examples markdown files.
 Other markdown from the docs folder are used as is.
-mkdocs is used to build the documentation site for production and server it in debug. It has a live reload and the markdown files can be looked at in order to understand why things are shown as they do.
+[MkDocs](https://www.mkdocs.org/) is used to build the documentation site for production and server it in debug. It has a live reload and the markdown files can be looked at in order to understand why things are shown as they do.