           , ''
         )
 
-    # - The main toggle handler. Hooked into by `offsetOnTriggerMouseMove`.
+    # `_onTriggerMouseMove` is actually the main tip toggling handler. To
+    # explain, first we take into account of child elements triggering the mouse
+    # event by deducing the event's actual `$trigger` element. Then we
+    # `wakeByTrigger` if needed, and provide a completion callback that will
+    # properly update the tip offset per `offsetOnTriggerMouseMove` and
+    # `isDirection`. Also note that `cursorHeight` gets factored in.
     _onTriggerMouseMove: (event) ->
       return no if not event.pageX?
       $trigger = if (

        )
      )

    # Methods

    # - The main toggler. Takes in a callback, which is usually to update position.
    #   The toggling and main changes only happen if the delay is passed.
    #   1. Store current trigger info.
    #   2. Go directly to the position updating if no toggling is needed.
    #   3. Don't toggle if awake or waking, or if event isn't `truemouseenter`.
    #   4. If we are in the middle of sleeping, stop and speed up our waking
    #      transition.
    #   5. Update our trigger cache.
    wakeByTrigger: ($trigger, event, onWake) ->
      # - Check.
      triggerChanged = not $trigger.is @_$currentTrigger
      if triggerChanged
        @_inflateByTrigger $trigger
        @_$currentTrigger = $trigger
      # - Guard.
      if @_state is 'awake' and onWake?
        onWake()
        @debugLog 'quick update'
        return yes
      if event? then @debugLog event.type
      return no if @_state in ['awake', 'waking']
      # - Prepare.
      delay = @ms.delay.in
      duration = @ms.duration.in
      wake = =>
        @onShow triggerChanged, event
        @$tip.fadeIn duration, =>


  # Tip API
  # -------
  # Note that most of the interface is intended as protected.
  class Tip

    # The base constructor mostly does setup work that uses other subroutines
    # when needed. Note that we're also keeping `$triggers` and `$context` as
    # properties.
    constructor: (@$triggers, options, @$context) ->
      # Per convention, bind handler methods here.
      _.bindAll @, '_onTriggerMouseMove', '_setBounds'
      # Extend self with `options`.  
      # See default options for property names.
      $.extend (deep = yes), @, options
      # The element represented by this API is `$tip`. We build it.
      @$tip = $ '<div>'
      # Infer `doStem` and `doFollow` flags from respective `classNames` entries.
      @doStem = @classNames.stem isnt ''
      @doFollow = @classNames.follow isnt ''
      # `_state` toggles between: `awake`, `asleep`, `waking`, `sleeping`. The
      # use case behind these states is the tip will remain visible and `awake`
      # as long as there is a high enough frequency of relevant mouse activity.
      # This is achieved with a simple base implementation around timers
      # `_sleepCountdown` and `_wakeCountdown`.
      @_state = 'asleep'
      @_wakeCountdown = null
      @_sleepCountdown = null
      # `_$currentTrigger` helps manage trigger-related state.
      @_$currentTrigger = null
      # Tip instances start off rendered and bound.
      @_render()
      @_bind()
      # Process `$triggers` and setup content, event, and positioning aspects.
      @$triggers.each (i, el) =>
        $trigger = $ el
        $trigger.addClass @classNames.trigger
