Integration with tsd-jsdoc for generating typings

[bampakoa]

References #5717

This PR contains modifications in the jsdoc block tags so that we can nicely integrate with tsd-jsdoc and create a typings file for the library. Initially we are adding missing jsdoc block tags in order for tsd-jsdoc to have a first time pass from each subfolder of Sources directory and compile successfully.

• Core
• Renderer
• Scene

[cesium-concierge]

@bampakoa, thanks for the pull request! Maintainers, we have a signed CLA from @bampakoa, so you can review this at any time.

⚠️ I noticed that CHANGES.md has not been updated. If this change updates the public API in any way, fixes a bug, or makes any non-trivial update, please add a bullet point to CHANGES.md and comment on this pull request so we know it was updated. For more info, see the Pull Request Guidelines.

---

I am a bot who helps you make Cesium awesome! Contributions to my configuration are welcome.

🌍 🌎 🌏

[hpinkos]

Thanks for the pull request @bampakoa! These changes look good so far. Let us know when this is ready for a full review

[bampakoa]

@hpinkos I have added the namespace block in AutomaticUniforms file as stated in Using @alias for an object literal example. I am not really sure if namespace should be added, but something was missing there and I think namespace is a good fit. What do you think?

[hpinkos]

Hmm, @namespace seems like it might be the right thing to do there but I'm not sure either. @mramato what do you think?

[bampakoa]

@hpinkos I have noticed that Cesium uses internalConstructor block tag in various pieces of the code, which is not part of the standard JSDoc syntax? What is this all about?

[hpinkos]

@bampakoa this is one of our custom tags. You can see the others here: https://github.com/AnalyticalGraphicsInc/cesium/blob/master/Tools/jsdoc/cesiumTags.js

internalConstructor is an alias of class. We use it to denote things that shouldn't be instantiated by the end user. For example Billboard has a constructor, but you should never call new Billboard(). Instead, you create one using billboardCollection.add({ billboardProperties }).

[bampakoa]

@hpinkos I added also class block tag where internalConstructor is used so that jsdoc can differentiate the actual tag.

PR is now ready for review. There are a lot of warnings yet but tsd-jsdoc is now running successfully with Cesium repo.

[hpinkos]

These shouldn't be needed. We don't do this for our prototype functions in any other class

[bampakoa]

I have seen it in various places of the code https://github.com/AnalyticalGraphicsInc/cesium/search?p=4&q=memberOf&type=Code and I thought that tsd-jsdoc was failing due to this one. Is there any similar file such as LabelCollection that I could check out instead?

[hpinkos]

Yes, we use @memberof for properties added to prototype via defineProperties but shouldn't need it for class methods

[hpinkos]

BillboardCollection is very similar to LabelCollection

[bampakoa]

Thanks for the clarification 😃 I will update the PR accordingly.

[hpinkos]

I just had that one comment. These changes look fine to me. Does anyone else want to take a look? I'll merge this by the end of the week if no one else has comments

[bampakoa]

@hpinkos the changes in the PR are available for review

[hpinkos]

Everything looks good @bampakoa! I can confirm the documentation builds correctly.

[hpinkos]

I'll add a comment to CHANGES.md in master

[bampakoa]

I would have done it, as @cesium-concierge notified me about it, but I thought it was not meant to be an actual change 🤔

[hpinkos]

No worries 😄 I just decided to do it to save some additional back and forth. I wasn't sure if it warranted a line in CHANGES initially, but I think other users using TypeScript will be interested in this so I decided to add it. Thanks again for the contribution!