playcanvas/playcanvas-jsdoc-template

JSDoc template for PlayCanvas

PlayCanvas JSDoc Template

This is a JSDoc 3.x and 4.x compatible template for the PlayCanvas API Reference. It is generated automatically during engine publishing process and hosted on: https://developer.playcanvas.com/api/

How to build

Ensure you have Node.js installed. Then, install all of the required Node.js dependencies:

npm install

Then you can build CSS styles:

npm run build

To test static html files, you need to use PlayCanvas Engine repository. Clone https://github.com/playcanvas/engine besides this repository:

./playcanvas-jsdoc-template/
./engine/

Then edit ./engine/conf-api.json, field opts.template to: "../playcanvas-jsdoc-template" so it will use your local copy of templates for building the docs, and then in ./engine/ run:

npm run docs

Static files will be generated to:

./engine/docs/

These can be served by the web server of your choice or viewed directly by opening ./engine/docs/index.html in a web browser.

playcanvas-jsdoc-template's Issues

Broken links to builtin types

All primitive builtin types (number, boolean, string, object, undefined, null etc) have broken links. Instead of linking to a nonexistent PlayCanvas API type they should link to an official page at MDN Web Docs.

For example number links currently to https://developer.playcanvas.com/en/api/number.html, instead of https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number:

API Reference is missing Discord link

Comments

The PlayCanvas website is missing a Discord link in the API Reference header, unlike the User Manual + Tutorials headers' which do include it.

User Manual

Tutorials

API Reference

API Link

https://developer.playcanvas.com/en/api/

Invalid type for array of number array

The CurveSet constructor has a parameter curveKeys of type Array.[]. The type should instead be displayed as number[][]. See screenshot:

Analytics might not be collecting data

Google has stopped processing UA on July 1st and now requires GA4 analytics.

When I was reading through, I saw UA in a template.

Reference here:
https://support.google.com/analytics/answer/13467533?hl=en#zippy=%2Cin-this-article

The template was:
https://github.com/playcanvas/playcanvas-jsdoc-template/blob/eb50e06352cf25d84d04626da51830c37aaaa7da/tmpl/analytics.hbs

The existing code looks like this and uses UA-XXX tag.

<script>
  (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
  (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
  m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
  })(window,document,'script','//www.google-analytics.com/analytics.js','ga');

  ga('create', 'UA-23605814-1', 'auto');
  ga('send', 'pageview');
</script>

GA4 looks like this and uses a G-XXXXX tag.

<script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXX"></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag() { dataLayer.push(arguments); }
  gtag('js', new Date());

  gtag('config', 'G-XXXXXXXX');
</script>

JSDoc template uses `taffydb` blocking upgrade to JSDoc 4.0.x in dependant projects

This JSDoc template uses taffydb blocking upgrade to JSDoc 4.0 in dependant projects.

Instructions for upgrading it while maintaining backward compatibility with 3.x are provided here:
https://github.com/jsdoc/jsdoc/tree/main/packages/jsdoc-salty#use-salty-in-a-jsdoc-template

Impact:

The "playcanvas-engine" project can not be updated to JSDoc 4.0 until this template is remediated. It might still be blocked by the "jsdoc-tsimport-plugin" dependency after the proposed resolution below.

This taffydb sub dependency in this project gives a high vulnerability warning when installing dependencies in "playcanvas-engine". It can NOT be exploited in any build product. The warning is only distracting at best.

For reference:
https://github.com/jsdoc/jsdoc/tree/main/packages/jsdoc-salty#taffydb-jsdoc-and-security

Resolution

I propose:

• submitting a PR to upgrade this JSDoc template to use @jsdoc/salty (the replacement for taffydb) following the template upgrade instructions from the jsdoc project
• remediate issues
• update tests

Notes

• if accepted and tested, I'll need help to increment the package version and publish the update to npm

Move [read only] to be next to the property as it is not clear at the moment

Looking at the list of properties, it is not clear if the read only tag is for the property above or below.

@typedef causes blank type definitions to appear in the generated docs

Recently, the following has been added to the PlayCanvas Engine codebase to aid with IntelliSense/TypeScript declaration generation:

/** @typedef {import('./graphics-device.js').GraphicsDevice} GraphicsDevice */

This is causing a new Type Definitions section to appear in the generated docs:

The detailed reference for these types is blank:

These seem to be overriding/overwriting the original, full API ref pages for those classes.

Improve README.md

Readme now does not contain any information.

Please add:

1. How to build (with local engine as well)
2. How to test with/without local server