diff --git a/js/style/style.js b/js/style/style.js
index b5824cc5f1..2dd0400bd0 100644
--- a/js/style/style.js
+++ b/js/style/style.js
@@ -317,9 +317,10 @@ Style.prototype = util.inherit(Evented, {
     },
 
     /**
-     * Get a layer by id.
-     * @param {string} id id of the desired layer
-     * @returns {Layer} layer
+     * Return the style layer object with the given `id`.
+     *
+     * @param {string} id - id of the desired layer
+     * @returns {?Object} a layer, if one with the given `id` exists
      * @private
      */
     getLayer: function(id) {
diff --git a/js/ui/map.js b/js/ui/map.js
index 14188aac06..aaf3c22ed0 100644
--- a/js/ui/map.js
+++ b/js/ui/map.js
@@ -503,8 +503,9 @@ util.extend(Map.prototype, /** @lends Map.prototype */{
      * specified layer via a `ref` property are also removed.
      *
      * @param {string} id layer id
+     * @throws {Error} if no layer with the given `id` exists
      * @fires layer.remove
-     * @returns {Map} this
+     * @returns {Map} `this`
      */
     removeLayer: function(id) {
         this.style.removeLayer(id);
@@ -515,8 +516,8 @@ util.extend(Map.prototype, /** @lends Map.prototype */{
     /**
      * Return the style layer object with the given `id`.
      *
-     * @param {string} id layer ID
-     * @returns {Object}
+     * @param {string} id layer id
+     * @returns {?Object} a layer, if one with the given `id` exists
      */
     getLayer: function(id) {
         return this.style.getLayer(id);