From ce1e98de78e860cd39c0c7faa3c12f2ecdf1fa1f Mon Sep 17 00:00:00 2001
From: Mal Wood-Santoro <mal.wood@mapbox.com>
Date: Mon, 20 Apr 2020 15:29:08 -0700
Subject: [PATCH] [docsprint] Clarify how map.moveLayer works (#9566)

* clarify how map.moveLayer works

* fix wording

* small wording fix

* fix id capitalization
---
 src/ui/map.js | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/src/ui/map.js b/src/ui/map.js
index 4e12e769153..68108061a37 100755
--- a/src/ui/map.js
+++ b/src/ui/map.js
@@ -1790,13 +1790,12 @@ class Map extends Camera {
      * Moves a layer to a different z-position.
      *
      * @param {string} id The ID of the layer to move.
-     * @param {string} [beforeId] The ID of an existing layer to insert the new layer before.
-     *   If this argument is omitted, the layer will be appended to the end of the layers array.
+     * @param {string} [beforeId] The ID of an existing layer to insert the new layer before. When viewing the map, the `id` layer will appear beneath the `beforeId` layer. If `beforeId` is omitted, the layer will be appended to the end of the layers array and appear above all other layers on the map.
      * @returns {Map} `this`
      *
      * @example
-     * // Move a layer with ID 'label' before the layer with ID 'waterways'.
-     * map.moveLayer('label', 'waterways');
+     * // Move a layer with ID 'polygon' before the layer with ID 'country-label'. The `polygon` layer will appear beneath the `country-label` layer on the map.
+     * map.moveLayer('polygon', 'country-label');
      */
     moveLayer(id: string, beforeId?: string) {
         this.style.moveLayer(id, beforeId);