docstrings: Refactor interactive layers, implements #4583 (#4585)

build/docs-index.leafdoc

@@ -52,6 +52,7 @@ This file just defines the order of the classes in the docs.
 @class Class
 @class Evented
 @class Layer
+@class Interactive layer
 @class Control
 @class Handler
 @class Projection

build/leafdoc-templates/html.hbs

@@ -116,6 +116,7 @@
 				<li><a href="#class">Class</a></li>
 				<li><a href="#evented">Evented</a></li>
 				<li><a href="#layer">Layer</a></li>
+				<li><a href="#interactive-layer">Interactive layer</a></li>
 				<li><a href="#control">Control</a></li>
 				<li><a href="#handler">Handler</a></li>
 				<!--<li><a class="nodocs" href="#">IFeature</a></li>-->

src/layer/ImageOverlay.js

@@ -1,7 +1,7 @@
 /*
  * @class ImageOverlay
  * @aka L.ImageOverlay
- * @inherits Layer
+ * @inherits Interactive layer
  *
  * Used to load and display a single image over specific bounds of the map. Extends `Layer`.
  *
@@ -28,7 +28,7 @@ L.ImageOverlay = L.Layer.extend({
 		alt: '',
 
 		// @option interactive: Boolean = false
-		// If `true`, the image overlay will emit mouse events when clicked or hovered.
+		// If `true`, the image overlay will emit [mouse events](#interactive-layer) when clicked or hovered.
 		interactive: false,
 
 		// @option attribution: String = null

src/layer/Layer.Interactive.leafdoc

@@ -0,0 +1,32 @@
+@class Interactive layer
+@inherits Layer
+
+Some `Layer`s can be made interactive - when the user interacts
+with such a layer, mouse events like `click` and `mouseover` can be handled.
+Use the [event handling methods](#evented-method) to handle these events.
+
+@option interactive: Boolean = true
+If `false`, the layer will not emit mouse events and will act as a part of the underlying map.
+
+@section Mouse events
+
+@event click: MouseEvent
+Fired when the user clicks (or taps) the layer.
+
+@event dblclick: MouseEvent
+Fired when the user double-clicks (or double-taps) the layer.
+
+@event mousedown: MouseEvent
+Fired when the user pushes the mouse button on the layer.
+
+@event mouseover: MouseEvent
+Fired when the mouse enters the layer.
+
+@event mouseout: MouseEvent
+Fired when the mouse leaves the layer.
+
+@event contextmenu: MouseEvent
+Fired when the user right-clicks on the layer, prevents
+default browser context menu from showing if there are listeners on
+this event. Also fired on mobile when the user holds a single touch
+for a second (also called long press).

src/layer/marker/Marker.js

@@ -1,6 +1,6 @@
 /*
  * @class Marker
- * @inherits Layer
+ * @inherits Interactive layer
  * @aka L.Marker
  * L.Marker is used to display clickable/draggable icons on the map. Extends `Layer`.
  *
@@ -20,8 +20,7 @@ L.Marker = L.Layer.extend({
 		// Icon class to use for rendering the marker. See [Icon documentation](#L.Icon) for details on how to customize the marker icon. Set to new `L.Icon.Default()` by default.
 		icon: new L.Icon.Default(),
 
-		// @option interactive: Boolean = true
-		// If `false`, the marker will not emit mouse events and will act as a part of the underlying map.
+		// Option inherited from "Interactive layer" abstract class
 		interactive: true,
 
 		// @option draggable: Boolean = false
@@ -64,31 +63,6 @@ L.Marker = L.Layer.extend({
 		nonBubblingEvents: ['click', 'dblclick', 'mouseover', 'mouseout', 'contextmenu']
 	},
 
-	/* @section
-	 *
-	 * You can subscribe to the following events using [these methods](#evented-method).
-	 *
-	 * @event click: MouseEvent
-	 * Fired when the user clicks (or taps) the marker.
-	 *
-	 * @event dblclick: MouseEvent
-	 * Fired when the user double-clicks (or double-taps) the marker.
-	 *
-	 * @event mousedown: MouseEvent
-	 * Fired when the user pushes the mouse button on the marker.
-	 *
-	 * @event mouseover: MouseEvent
-	 * Fired when the mouse enters the marker.
-	 *
-	 * @event mouseout: MouseEvent
-	 * Fired when the mouse leaves the marker.
-	 *
-	 * @event contextmenu: MouseEvent
-	 * Fired when the user right-clicks on the marker.
-	 */
-
-
-
 	/* @section
 	 *
 	 * In addition to [shared layer methods](#Layer) like `addTo()` and `remove()` and [popup methods](#Popup) like bindPopup() you can also use the following methods:

src/layer/vector/Path.js

@@ -1,7 +1,7 @@
 /*
  * @class Path
  * @aka L.Path
- * @inherits Layer
+ * @inherits Interactive layer
  *
  * An abstract class that contains options and constants shared between vector
  * overlays (Polygon, Polyline, Circle). Do not use it directly. Extends `Layer`.
@@ -62,8 +62,7 @@ L.Path = L.Layer.extend({
 
 		// className: '',
 
-		// @option interactive: Boolean = true
-		// If `false`, the vector will not emit mouse events and will act as a part of the underlying map.
+		// Option inherited from "Interactive layer" abstract class
 		interactive: true
 	},