Note that prewarm() is synchronous (#10998)

HeyStenson · SnailBones · rreusser · web-flow · commit 7dc8df6ca4df · 2021-09-14T14:37:52.000-06:00
* note that prewarm is synchronous
* Applying suggestions so we can get this into v2.5
Co-authored-by: Aidan H &lt;aidan.hendrickson@mapbox.com&gt;
Co-authored-by: Ricky Reusser &lt;rreusser@users.noreply.github.com&gt;
diff --git a/src/index.js b/src/index.js
@@ -57,16 +57,18 @@ const exported = {
      * used, must be set before `prewarm()` is called to have an effect.
      *
      * By default, the lifecycle of these resources is managed automatically, and they are
-     * lazily initialized when a Map is first created. By invoking `prewarm()`, these
-     * resources will be created ahead of time, and will not be cleared when the last Map
-     * is removed from the page. This allows them to be re-used by new Map instances that
+     * lazily initialized when a `Map` is first created. Invoking `prewarm()` creates these
+     * resources ahead of time and ensures they are not cleared when the last `Map`
+     * is removed from the page. This allows them to be re-used by new `Map` instances that
      * are created later. They can be manually cleared by calling
-     * `mapboxgl.clearPrewarmedResources()`. This is only necessary if your web page remains
-     * active but stops using maps altogether.
+     * `mapboxgl.clearPrewarmedResources()`. This is only necessary if your web page
+     * remains active but stops using maps altogether. `prewarm()` is idempotent
+     * and has guards against being executed multiple times, and any resources
+     * allocated by `prewarm()` are created synchronously.
      *
-     * This is primarily useful when using Mapbox GL JS maps in a single page app, in which a user
-     * would navigate between various views that can cause Map instances to constantly be
-     * created and destroyed.
+     * This is primarily useful when using Mapbox GL JS maps in a single page app,
+     * in which a user navigates between various views, resulting in
+     * constant creation and destruction of `Map` instances.
      *
      * @function prewarm
      * @example
