Migrate JSDocs to TSDocs #2756

HarelM · 2023-06-28T18:14:19Z

Resolves #2150
Resolves #2776
This will be a PR that will be merged when the branch is ready and all comments are migrated.
Please open PRs against this PR/branch.

CI - will be solved by
Enable TSdocs lint? (mainly @param hyphen?)
Make sure the docs don't have warning when they build
remove @memberof @instanceof @inherits, @typedef, @name, @function, @instance, @property
Event are linking to invalid location and in general are not properly structured in terms of docs, I'll need to see how to properly solve this. Not a blocker
Make sure example links are working and are backward compatible (?)
Update the main readme with the relevant links

* 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

…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 * Fix lint

* Changes to docs contribution * don't link for better review

* Migrated marker and popup * Fix lint * Code review fixes * Added missing marker options object * Fix lint and tests * Fix typo * remove unneeded lint comment.

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] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

* Fix sources * Added typedoc * Fix custom style layer

* 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

codecov-commenter · 2023-07-04T15:01:12Z

Codecov Report

Patch coverage: 89.21% and project coverage change: +0.03 🎉

Comparison is base (30c0e1d) 73.90% compared to head (8946e89) 73.93%.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2756      +/-   ##
==========================================
+ Coverage   73.90%   73.93%   +0.03%     
==========================================
  Files         238      238              
  Lines       18980    18968      -12     
  Branches     4282     4281       -1     
==========================================
- Hits        14027    14024       -3     
+ Misses       4953     4944       -9

Impacted Files	Coverage Δ
src/data/bucket.ts	`92.85% <ø> (ø)`
src/data/bucket/circle_bucket.ts	`78.16% <ø> (ø)`
src/data/bucket/line_bucket.ts	`58.23% <ø> (ø)`
src/data/bucket/symbol_bucket.ts	`50.61% <ø> (ø)`
src/data/evaluation_feature.ts	`100.00% <ø> (ø)`
src/data/extent.ts	`100.00% <ø> (ø)`
src/data/feature_index.ts	`32.88% <ø> (ø)`
src/data/index_array_type.ts	`100.00% <ø> (ø)`
src/data/load_geometry.ts	`100.00% <ø> (ø)`
src/data/program_configuration.ts	`32.28% <ø> (ø)`
... and 110 more

☔ View full report in Codecov by Sentry.
📢 Do you have feedback about the report comment? Let us know in this issue.

HarelM · 2023-07-05T10:33:14Z

This is ready for review, basically most if not all of the content here was reviewed in the PRs that where merged to this branch.

birkskyum · 2023-07-05T10:58:23Z

Should #2802 be merged in first?

* Added comments to reduce warnings * Fix most of the warnings in the build process

HarelM · 2023-07-05T11:11:15Z

Yes, and also the CI part, as part of the #2776 bounty.
But all the PRs are against this branch, if this is not approved I won't be able to merge.
If you want to re-review everything again that fine too 😀

birkskyum · 2023-07-05T11:21:10Z

Would you do the @param hyphen replacement as part of this?

HarelM · 2023-07-05T11:25:51Z

IDK, I might as part of enabling the tsdocs lint stuff..

HarelM · 2023-07-05T15:29:54Z

I've finished with most of the tsdoc errors.
I'm giving the events a final touch.
Hopefully a new doc site by the end of the week.

@Private

* 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

HarelM · 2023-07-05T20:40:06Z

I'm struggling with what appears to be a bug with the markdown plugin:
typedoc2md/typedoc-plugin-markdown#448

I'll leave this for now as I would like to have more groups in the main intro file and currently something doesn't like me there...

HarelM · 2023-07-06T07:08:29Z

The following might also be a solution to the above issue if I don't get any feedback on the issue I opened:
https://github.com/hughrawlinson/typedoc-to-markdown
It's a single file converting the typedoc json output to markdown, which seems a lot simpler.

birkskyum · 2023-07-06T08:51:35Z

I only see these items in the toc - should I expect to see also the classes/interface/enums?

birkskyum · 2023-07-06T08:56:13Z

If it's appear to be completely impossible to repair the markdown/mkdocs flow, there is also a potential option to explore if any of the other typedoc plugins work (docusaurus or even hugo) to figure if it's the tsdocs output that's off. Don't know how much adaption of examples that would be though.

HarelM · 2023-07-06T09:57:17Z

The problem is with the markdown plugin, as you can see in the linked issue.
I've checked the typedoc json output and it is valid and with the relevant group.
Docusurus also uses this ("buggy") plugin, so we'll be facing the same issue.
The problem is with the markdown generation, other platforms won't be able to help with this I believe...

HarelM · 2023-07-06T09:58:48Z

Since converting the json file to markdown files shouldn't be complicated, and there is already some code that does that, it might be a possible solution. But's let's wait a bit to see if there's a response.

HarelM · 2023-07-06T12:43:19Z

Event Related was now added by adding a config flag to place everything in a different file.
There is still a need to fix the MapEvent docs as they are scrambled due to having @see and @exmaple one after the other.
And also improve the docs above the on to link to the relevant places.
I still need to think about how to improve this.
Also the main readme is not pointing relatively to the docs which I need to fix as well.
These are minor fixes, the last part of all this is the CI.

* Added Geography and Geometry * Fix lint

HarelM · 2023-07-06T21:00:02Z

With current version the events are now defined in two tables with the MapLayerEventType and MapEventType.
I have removed the links in the Map#on method as they didn't point anywhere and added above that table the relevant link.
I'm good with how it turned out.
Last thing is the main readme and the CI.
Overall this is almost complete.

birkskyum · 2023-07-08T11:07:11Z

All the links inside of the module, like:
https://maplibre.org/maplibre-gl-js/docs/API/classes/maplibregl.AttributionControl/

Was before found at:
https://maplibre.org/maplibre-gl-js-docs/api/markers/#attributioncontrol

Is there a migration strategy for that?

HarelM · 2023-07-08T11:13:18Z

The main links that I believe we will be able to keep are the examples bybredirecting maplibre-gl-js-docs to maplibre-gl-js/docs
I don't think I have a good idea how to keep the old link to classes etc, especially since it's case sensitive and the old links are lowercase...
Having said that, I'm OK with it, classes can change name etc and links to classes my break over time.

* 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

HarelM · 2023-07-08T17:30:06Z

I'll merge this and create a pre-release to see that everything is working asv expected.
Once everything is working I'll update the condition not to publish the docs on pre-release.

birkskyum · 2023-07-08T17:35:36Z

Sounds good. I did btw. try the @next version of the markdown plugin, but things are breaking, and it's also behind the master branch with 60+ commits, so it's probably best to proceed with the current version.

krishnaglodha approved these changes Jun 29, 2023

View reviewed changes

HarelM and others added 16 commits July 4, 2023 10:40

Some examples of conversion

23c966a

More experiments

4be14c0

Fix group name

6bc41a3

Fix lint

9939d8a

made basic UI changes (#2755)

b2f6de1

Move more comments to their right place

c249141

Remove more tsdocs comments

c2bfc2d

Fix lint, complete map jsdocs removal

22a5b05

Fix lint, remove return types from jsdocs comments.

f1a2977

Js ts controls (#2777)

a8b2793

* 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

Added handlers to the docs (#2778)

7745d70

* Added handlers to the docs * Fix lint

Small changes to the docs contribution guide (#2791)

433ed08

* Changes to docs contribution * don't link for better review

Migrated popup and marker (#2790)

1696536

* Migrated marker and popup * Fix lint * Code review fixes * Added missing marker options object * Fix lint and tests * Fix typo * remove unneeded lint comment.

Fix sources (#2795)

661b5f7

* Fix sources * Added typedoc * Fix custom style layer

HarelM force-pushed the jsdocs-tsdocs branch from 280c9d4 to 661b5f7 Compare July 4, 2023 10:46

HarelM added 4 commits July 4, 2023 15:11

Fix test, add comments

824503a

fix grammer spelling

b1f880f

More minor fixes

5dbfe10

HarelM marked this pull request as ready for review July 5, 2023 10:31

HarelM requested a review from birkskyum July 5, 2023 10:32

TSDocs JSDocs migration: build warning removal (#2802)

e3adb3c

* Added comments to reduce warnings * Fix most of the warnings in the build process

birkskyum approved these changes Jul 5, 2023

View reviewed changes

HarelM added 2 commits July 5, 2023 22:30

TSDocs lint (#2804)

18fc811

* 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

0f5934a

Fix lint

6240233

HarelM mentioned this pull request Jul 6, 2023

Documentation: Map extends Camera #2806

Closed

Fix the event related issue

8946e89

birkskyum approved these changes Jul 6, 2023

View reviewed changes

HarelM added 2 commits July 6, 2023 17:07

Added Geography and Geometry group (#2808)

297d485

* Added Geography and Geometry * Fix lint

Finished the event documentation

1c84ad4

Fix lint

7a2dc16

Main docs readme links fixes and CI (#2813)

fbdfcba

* 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.

c0e8daf

HarelM merged commit f329d91 into main Jul 8, 2023
14 checks passed

HarelM deleted the jsdocs-tsdocs branch July 8, 2023 21:08

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Migrate JSDocs to TSDocs #2756

Migrate JSDocs to TSDocs #2756

HarelM commented Jun 28, 2023 •

edited

codecov-commenter commented Jul 4, 2023 •

edited

HarelM commented Jul 5, 2023

birkskyum commented Jul 5, 2023

HarelM commented Jul 5, 2023

birkskyum commented Jul 5, 2023

HarelM commented Jul 5, 2023

HarelM commented Jul 5, 2023

HarelM commented Jul 5, 2023

HarelM commented Jul 6, 2023

birkskyum commented Jul 6, 2023

birkskyum commented Jul 6, 2023

HarelM commented Jul 6, 2023

HarelM commented Jul 6, 2023 •

edited

HarelM commented Jul 6, 2023

HarelM commented Jul 6, 2023

birkskyum commented Jul 8, 2023 •

edited

HarelM commented Jul 8, 2023

HarelM commented Jul 8, 2023

birkskyum commented Jul 8, 2023

Migrate JSDocs to TSDocs #2756

Migrate JSDocs to TSDocs #2756

Conversation

HarelM commented Jun 28, 2023 • edited

codecov-commenter commented Jul 4, 2023 • edited

Codecov Report

HarelM commented Jul 5, 2023

birkskyum commented Jul 5, 2023

HarelM commented Jul 5, 2023

birkskyum commented Jul 5, 2023

HarelM commented Jul 5, 2023

HarelM commented Jul 5, 2023

HarelM commented Jul 5, 2023

HarelM commented Jul 6, 2023

birkskyum commented Jul 6, 2023

birkskyum commented Jul 6, 2023

HarelM commented Jul 6, 2023

HarelM commented Jul 6, 2023 • edited

HarelM commented Jul 6, 2023

HarelM commented Jul 6, 2023

birkskyum commented Jul 8, 2023 • edited

HarelM commented Jul 8, 2023

HarelM commented Jul 8, 2023

birkskyum commented Jul 8, 2023

HarelM commented Jun 28, 2023 •

edited

codecov-commenter commented Jul 4, 2023 •

edited

HarelM commented Jul 6, 2023 •

edited

birkskyum commented Jul 8, 2023 •

edited