Fix buildModuleUrl.setBaseUrl and .getCesiumBaseUrl in JSDoc/TypeScript

[puxiao]

Issue 8922 8924

Description

If we use TypeScript, we will encounter the following problems.

import { buildModuleUrl } from 'cesium'

buildModuleUrl.setBaseUrl('./static/Cesium/')
buildModuleUrl.getCesiumBaseUrl()

PROBLEMS:

Property 'setBaseUrl' does not exist on type '(relativeUrl: string) => string'.
Property 'getCesiumBaseUrl' does not exist on type '(relativeUrl: string) => string'.

Why?

Source/Core/buildModuleUrl.js

/**
 * Given a relative URL under the Cesium base URL, returns an absolute URL.
 * @function
 *
 * ...
 */
function buildModuleUrl(relativeUrl) {
  ...
}



/**
 * Sets the base URL for resolving modules.
 * @param {String} value The new base URL.
 */
buildModuleUrl.setBaseUrl = function (value) {
  ...
};

/**
 * Gets the base URL for resolving modules.
 */
buildModuleUrl.getCesiumBaseUrl = getCesiumBaseUrl;

We can see that:

1. buildModuleUrl is a function
2. buildModuleUrl also is a namespace

When we execute the command build-ts, this is very confusing for JSDoc.

Cesium.d.ts

/**
 * Given a relative URL under the Cesium base URL, returns an absolute URL.
 * @example
 * ...
 */
export function buildModuleUrl(relativeUrl: string): string;

We can see that buildModuleUrl.setBaseUrl and buildModuleUrl.getCesiumBaseUrl is not exported.

Wrong solution

I have tried but failed.

+ /** @namespace buildModuleUrl */

 /**
  * @function
  */
 function buildModuleUrl(relativeUrl) {
   ...
 }


 /**
+ * @memberof buildModuleUrl
  * ...
  */
 buildModuleUrl.setBaseUrl = function (value) {
   ...
 };

 /**
+ * @memberof buildModuleUrl
  * ...
  */
 buildModuleUrl.getCesiumBaseUrl = getCesiumBaseUrl;

yarn run build-ts

Cesium.d.ts

export namespace buildModuleUrl {
    /**
     * ...
     */
    function setBaseUrl(value: string): void;
    /**
     * ...
     */
    function getCesiumBaseUrl(): Resource;
}

This time buildModuleUrl.setBaseUrl and buildModuleUrl.getCesiumBaseUrl is exported.

But export function buildModuleUrl has disappeared.

Emm.... I'm tired, destroy it.

The right solution

After unremitting efforts, I finally found a solution.

https://groups.google.com/g/jsdoc-users/c/1Md5S8j2ZI4

1. We use buildModuleUrl to represent the function
2. We use buildModuleUrl(1) to represent the namespace

Source/Core/buildModuleUrl.js

  /**
   * Given a relative URL under the Cesium base URL, returns an absolute URL.
+  * @function buildModuleUrl
   *
   * ...
   */
  function buildModuleUrl(relativeUrl) {
    ...
  }

+ /** @namespace buildModuleUrl(1) */

  /**
+  * @function setBaseUrl
+  * @memberof buildModuleUrl(1)
   * ...
   */
  buildModuleUrl.setBaseUrl = function (value) {
    ...
  };

  /**
+  * @function getCesiumBaseUrl
+  * @memberof buildModuleUrl(1)
   * ...
   */
  buildModuleUrl.getCesiumBaseUrl = getCesiumBaseUrl;

yarn run build-ts

Wow...

/**
 * Given a relative URL under the Cesium base URL, returns an absolute URL.
 * @example
 * var viewer = new Cesium.Viewer("cesiumContainer", {
 *   imageryProvider: new Cesium.TileMapServiceImageryProvider({
 *   url: Cesium.buildModuleUrl("Assets/Textures/NaturalEarthII"),
 *   }),
 *   baseLayerPicker: false,
 * });
 * @param relativeUrl - The relative path.
 * @returns The absolutely URL representation of the provided path.
 */
export function buildModuleUrl(relativeUrl: string): string;

export namespace buildModuleUrl {
    /**
     * Sets the base URL for resolving modules.
     * @param value - The new base URL.
     * @returns void
     */
    function setBaseUrl(value: string): void;
    /**
     * Gets the base URL for resolving modules.
     * @returns The base URL for resolving modules.
     */
    function getCesiumBaseUrl(): Resource;
}

Perfect !!!

[cesium-concierge]

Thanks for the pull request @puxiao!

• ✔️ Signed CLA found.
• ❔ CHANGES.md was not updated.
  • If this change updates the public API in any way, please add a bullet point to CHANGES.md.
• ❔ Unit tests were not updated.
  • Make sure you've updated tests to reflect your changes, added tests for any new code, and ran the code coverage tool.

Reviewers, don't forget to make sure that:

• Cesium Viewer works.
• Works in 2D/CV.
• Works (or fails gracefully) in IE11.

[cesium-concierge]

Thanks again for your contribution @puxiao!

No one has commented on this pull request in 90 days. Maintainers, can you review, merge or close to keep things tidy?

I'm going to re-bump this in 90 days. If you'd like me to stop, just comment with @cesium-concierge stop. If you want me to start again, just delete the comment.

[puxiao]

@ebogo1
Please code review this pr.

[ggetz]

Thanks @puxiao! Unfortunately, this does not work correctly with the generated documentation (npm run generateDocumentation ). I see two buildModuleUrl entries and see the (1).

In other modules, we use @memberof without defining a namespace or using an explicit name for @function. Does that work in your case?

[ggetz]

Throughout the codebase, we omit the return tag if the return type is void.

[puxiao]

I've tried to use @memberof and @function, but it doesn't solve the problem.

Wrong solution

I have tried but failed.

• /** @namespace buildModuleUrl */

/**

• @function
  */
  function buildModuleUrl(relativeUrl) {
  ...
  }

/**

• • @memberof buildModuleUrl
  • ...
    */
    buildModuleUrl.setBaseUrl = function (value) {
    ...
    };

/**

• • @memberof buildModuleUrl
  • ...
    */
    buildModuleUrl.getCesiumBaseUrl = getCesiumBaseUrl;
    yarn run build-ts

Cesium.d.ts

export namespace buildModuleUrl {
/**
* ...
/
function setBaseUrl(value: string): void;
/*
* ...
*/
function getCesiumBaseUrl(): Resource;
}
This time buildModuleUrl.setBaseUrl and buildModuleUrl.getCesiumBaseUrl is exported.

But export function buildModuleUrl has disappeared.

[ggetz]

Thanks for taking a look @puxiao. Unfortunately, since this change breaks existing documentation, I don't think we can take it as is. Also, while this function is technically public, I don't believe we recommend it for use in your apps. What is the use case for using this function?

[puxiao]

Okay, I know.

Thanks.