 class Keymap
   Emitter.includeInto(this)
 
+  # Public:
+  #
+  # options - An {Object} with the following optional keys:
+  #   :defaultTarget - This will be used as the target of events whose target
+  #     is `document.body` to allow for a catch-all element when nothing is
+  #     focused
   constructor: (options) ->
     @defaultTarget = options?.defaultTarget
     @keyBindings = []
     @keystrokes = []
     @watchSubscriptions = {}
 
+  # Public: Unwatch all watched paths.
   destroy: ->
     for filePath, subscription of @watchSubscriptions
       subscription.off()

    target.dispatchEvent(commandEvent)
    not commandEvent.keyBindingAborted

  keyBindingsForKeystrokesAndTarget: (keystrokes, target) ->
    @keyBindings
      .filter (binding) ->
        binding.keystrokes.indexOf(keystrokes) is 0 \
          and target.webkitMatchesSelector(binding.selector)
      .sort (a, b) -> a.compare(b)

  # Public: Get the key bindings for a given command and optional target.
  #
  # params - An {Object} whose keys constrain the binding search:
  #   :command - A {String} representing the name of a command, such as
  #     'editor:backspace'
  #   :target - An optional DOM element constraining the search. If this
  #     parameter is supplied, the call will only return bindings that can be
  #     invoked by a KeyboardEvent originating from the target element.
  findKeyBindings: (params={}) ->
    {command, target} = params

    bindings = @keyBindings

    if command?
      bindings = bindings.filter (binding) -> binding.command is command

    if target?
      candidateBindings = bindings
      bindings = []
      element = target
      while element? and element isnt document
        matchingBindings = candidateBindings
          .filter (binding) -> element.webkitMatchesSelector(binding.selector)
          .sort (a, b) -> a.compare(b)
        bindings.push(matchingBindings...)
        element = element.parentElement
    bindings

  # Public: Translate a keydown event to a keystroke string.
  #
  # event - A {KeyboardEvent} of type 'keydown'

  #   so they can be removed later.
  # bindings - An {Object} whose top-level keys point at sub-objects mapping
  #   keystroke patterns to commands.
  addKeyBindings: (source, keyBindingsBySelector) ->
    for selector, keyBindings of keyBindingsBySelector
      @addKeyBindingsForSelector(source, selector, keyBindings)
