From c95cbc6b8061ce35acb530f6abd969c49d668567 Mon Sep 17 00:00:00 2001
From: Gabby Getz <gabby@cesium.com>
Date: Wed, 8 Feb 2023 16:03:05 -0500
Subject: [PATCH] Cleanup doc

---
 packages/engine/Source/Scene/Terrain.js | 50 +++++++++++++------------
 1 file changed, 26 insertions(+), 24 deletions(-)

diff --git a/packages/engine/Source/Scene/Terrain.js b/packages/engine/Source/Scene/Terrain.js
index 3dfdf84f7068..1ed77b5a7e71 100644
--- a/packages/engine/Source/Scene/Terrain.js
+++ b/packages/engine/Source/Scene/Terrain.js
@@ -37,15 +37,16 @@ async function handlePromise(instance, promise) {
  * @example
  * // Create
  * const viewer = new Cesium.Viewer("cesiumContainer", {
- *   terrainProvider: new Cesium.Terrain(Cesium.CesiumTerrainProvider.fromUrl("https://myTestTerrain.com"));
+ *   terrain: new Cesium.Terrain(Cesium.CesiumTerrainProvider.fromUrl("https://myTestTerrain.com"));
  * });
  *
  * @example
  * // Handle loading events
  * const terrain = new Cesium.Terrain(Cesium.CesiumTerrainProvider.fromUrl("https://myTestTerrain.com"));
  *
+ * scene.setTerrain(terrain);
+ *
  * terrain.readyEvent.addEventListener(provider => {
- *   scene.terrainProvider = provider;
  *   scene.globe.enableLighting = true;
  *
  *   terrain.provider.errorEvent.addEventListener(error => {
@@ -57,27 +58,27 @@ async function handlePromise(instance, promise) {
  *   alert(`Encountered an error while creating terrain! ${error}`);
  * });
  *
- * @param {Promise<TerrainProvider>} A promise which resolves to a terrain provider
+ * @param {Promise<TerrainProvider>} terrainProviderPromise A promise which resolves to a terrain provider
  */
-function Terrain(providerPromise) {
+function Terrain(terrainProviderPromise) {
   //>>includeStart('debug', pragmas.debug);
-  Check.typeOf.object("providerPromise", providerPromise);
+  Check.typeOf.object("terrainProviderPromise", terrainProviderPromise);
   //>>includeEnd('debug');
 
   this._provider = undefined;
   this._errorEvent = new Event();
   this._readyEvent = new Event();
 
-  handlePromise(this, providerPromise);
+  handlePromise(this, terrainProviderPromise);
 }
 
 Object.defineProperties(Terrain.prototype, {
   /**
    * Gets an event that is raised when the terrain provider encounters an asynchronous error.  By subscribing
    * to the event, you will be notified of the error and can potentially recover from it.  Event listeners
-   * are passed an instance of {@link TileProviderError}.
-   * @memberof TerrainProvider.prototype
-   * @type {Event<TerrainProvider.ErrorEvent>}
+   * are passed an instance of the thrown error.
+   * @memberof Terrain.prototype
+   * @type {Event<Terrain.ErrorEventCallback>}
    * @readonly
    */
   errorEvent: {
@@ -89,8 +90,8 @@ Object.defineProperties(Terrain.prototype, {
   /**
    * Gets an event that is raised when the terrain provider has been successfully created. Event listeners
    * are passed the created instance of {@link TerrainProvider}.
-   * @memberof TerrainProvider.prototype
-   * @type {Event<TerrainProvider.ReadyEvent>}
+   * @memberof Terrain.prototype
+   * @type {Event<Terrain.ReadyEventCallback>}
    * @readonly
    */
   readyEvent: {
@@ -120,7 +121,7 @@ Object.defineProperties(Terrain.prototype, {
  * @param {Object} [options] Object with the following properties:
  * @param {Boolean} [options.requestVertexNormals=false] Flag that indicates if the client should request additional lighting information from the server if available.
  * @param {Boolean} [options.requestWaterMask=false] Flag that indicates if the client should request per tile water masks from the server if available.
- * @returns {<Terrain>} A promise that resolves to the created CesiumTerrainProvider
+ * @returns {Terrain} An asynchronous helper object for a CesiumTerrainProvider
  *
  * @see Ion
  * @see createWorldTerrainAsync
@@ -128,13 +129,13 @@ Object.defineProperties(Terrain.prototype, {
  * @example
  * // Create Cesium World Terrain with default settings
  * const viewer = new Cesium.Viewer("cesiumContainer", {
- *   terrainProvider: Cesium.Terrain.fromWorldTerrain()
+ *   terrain: Cesium.Terrain.fromWorldTerrain()
  * });
  *
  * @example
  * // Create Cesium World Terrain with water and normals.
  * const viewer1 = new Cesium.Viewer("cesiumContainer", {
- *   terrainProvider: Cesium.Terrain.fromWorldTerrain({
+ *   terrain: Cesium.Terrain.fromWorldTerrain({
  *      requestWaterMask: true,
  *      requestVertexNormals: true
  *    });
@@ -142,18 +143,19 @@ Object.defineProperties(Terrain.prototype, {
  *
  * @example
  * // Handle loading events
- * const providerManager = Cesium.Terrain.fromWorldTerrain();
+ * const terrain = Cesium.Terrain.fromWorldTerrain();
  *
- * providerManager.readyEvent.addEventListener(provider => {
- *   viewer.terrainProvider = provider;
- *   viewer.scene.globe.enableLighting = true;
+ * scene.setTerrain(terrain);
  *
- *   providerManager.provider.errorEvent.addEventListener(error => {
+ * terrain.readyEvent.addEventListener(provider => {
+ *   scene.globe.enableLighting = true;
+ *
+ *   terrain.provider.errorEvent.addEventListener(error => {
  *     alert(`Encountered an error while loading terrain tiles! ${error}`);
  *   });
  * });
  *
- * providerManager.errorEvent.addEventListener(error => {
+ * terrain.errorEvent.addEventListener(error => {
  *   alert(`Encountered an error while creating terrain! ${error}`);
  * });
  */
@@ -161,9 +163,11 @@ Terrain.fromWorldTerrain = function (options) {
   return new Terrain(createWorldTerrainAsync(options));
 };
 
+export default Terrain;
+
 /**
  * A function that is called when an error occurs.
- * @callback Terrain.ErrorEvent
+ * @callback Terrain.ErrorEventCallback
  *
  * @this Terrain
  * @param {Error} err An object holding details about the error that occurred.
@@ -171,10 +175,8 @@ Terrain.fromWorldTerrain = function (options) {
 
 /**
  * A function that is called when the provider has been created
- * @callback Terrain.ReadyEvent
+ * @callback Terrain.ReadyEventCallback
  *
  * @this Terrain
  * @param {TerrainProvider} provider The created terrain provider.
  */
-
-export default Terrain;