docs: document classes implementing GeometryFactory

[MohammadShujaullah]

Fixes #12827

– Document classes implementing the GeometryFactory interface.

Description

This PR improves the documentation of GeometryFactory and its usage:

• Clarifies that GeometryFactory is an abstract interface-like type implemented by geometry description classes with a static createGeometry method.
• Adds @see links in GeometryFactory to the main implementing geometry classes.
• Expands GeometryInstance.options.geometry docs to explain Geometry vs GeometryFactory (e.g. RectangleGeometry, EllipsoidGeometry) and how createGeometry is used.

Testing plan

• npm test (or tests recommended in CONTRIBUTING)

Author checklist

• I have submitted a Contributor License Agreement
• [ ] I have added my name to CONTRIBUTORS.md
• I have updated CHANGES.md with a short summary of my change
• I have added or updated unit tests to ensure consistent code coverage
• I have updated the inline documentation, and included code examples where relevant
• I have performed a self-review of my code

[github-actions]

Thank you for the pull request, @MohammadShujaullah! Welcome to the Cesium community!

In order for us to review your PR, please complete the following steps:

• Send in a Contributor License Agreement (CLA)
• Add yourself to the contributors file

Review Pull Request Guidelines to make sure your PR gets accepted quickly.

[MohammadShujaullah]

@cla-bot check

[jjspace]

Thanks for the PR @MohammadShujaullah, just a couple small comments

[jjspace]

You shouldn't need to add the <p> tags yourself. This should be handled by JSDoc itself AFAIK.

[jjspace]

I don't believe this needs an alias since it matches the function name itself

[jjspace]

I'm kinda on the fence about the usefullness of this simply because it's such a big list. I could see it easily going out of sync with the actual classes. I don't think there's been much change in this area so maybe it doesn't matter.

@donmccurdy or @javagl this is sorta related to recent discussions we've had around classes and inheritance. Any thoughts here?

[donmccurdy]

Thank you @MohammadShujaullah for compiling the list! However I think I agree with @jjspace, I'd (personally) be hesitant to commit to maintaining such a list by hand.

I can't speak for every code editor, but using TypeScript language services in Zed, there are "Find All References" and "Go to Implementation" tools built into the editor. These don't work on GeometryFactory for me today (TS language service limitations with JSDoc probably), unless I either:

• (a) add @extends GeometryFactory annotations to the implementations, and also add type-only imports as described in Types: Enable incremental JSDoc type checking #13104
• (b) convert to ES6 classes

Getting that information out of the language server, and into published docs, might require more steps — if that's the goal. But at least we'd have confidence that the list will remain up to date.

If we do merge #13104, adding the missing @extends X or @implements X annotations could be a good next step?

[javagl]

No strong opinion on this particular case.

Pro:

• Consistency: Implementing classes are already listed in other cases (.e.g https://cesium.com/learn/cesiumjs/ref-doc/Property.html )
• Stability: It will not change. Or is anyone up for creating a new implementation of GeometryFactory?

Con:

• Maintenance (but that's a weak point, given the 'Stability' above)
• It may become obsolete with better tooling around TS/JSDoc (but that may take months or years...)

Some of the back-and-forth links are currently broken anyhow (e.g. InterpolationAlgorithm or Packable - see #11749 (comment) ). As long as we don't have a clean(er) concept of visibility and automatisms for generating such links, I think that adding the list here is OK, and be it only to know into which classes we'll have to insert @extends GeometryFactory after the corresponding tooling was set up 🤷‍♂️

[jjspace]

Thanks for the input @donmccurdy and @javagl. I think given the stability of this area which hasn't changed much I'm going to lean towards "any info is better than no info" for now. These can stay.

We should definitely look into improving this area in the future since things like this should be automated. This may come "free" or easier after some of the class and/or TS refactoring @donmccurdy mentioned but that's far outside the scope for this PR.