 autocompletion = require './autocompletion'
 
-module.exports = (e, opts = {}) ->
+module.exports = (e, opts = {}) -> # opts contains callbacks to ide.coffee
   b = (cssClasses, description) -> "<a href='#' class='#{cssClasses} tb-button' title='#{description}'></a>"
   ($e = $ e).html """
     <div class="toolbar debugger-toolbar">
-      #{[ # the first two buttons are placed on the right-hand side through CSS; in a floating window they are hidden
-        b 'tb-EP  last',    'Quit this function'
+      #{[
+        # The first two buttons are placed on the right-hand side through CSS.  In a floating window they are hidden.
+        # CSS classes "first" and "last" indicate button grouping.
+        b 'tb-EP  last',      'Quit this function'
         b 'tb-pop first',     'Edit in a floating window'
-        b 'tb-ER  first',    'Execute line'
-        b 'tb-TC',           'Trace into expression'
-        b 'tb-BK',           'Go back one line'
-        b 'tb-FD',           'Skip current line'
-        b 'tb-BH',           'Continue trace'
-        b 'tb-RM',           'Continue execution'
-        b 'tb-MA',           'Restart all threads'
-        b 'tb-ED',           'Edit name'
-        b 'tb-WI',           'Interrupt'
-        b 'tb-CBP',          'Clear trace/stop/monitor for this object'
-        b 'tb-LN  last',     'Toggle line numbers'
+        b 'tb-ER  first',     'Execute line'
+        b 'tb-TC',            'Trace into expression'
+        b 'tb-BK',            'Go back one line'
+        b 'tb-FD',            'Skip current line'
+        b 'tb-BH',            'Continue trace'
+        b 'tb-RM',            'Continue execution'
+        b 'tb-MA',            'Restart all threads'
+        b 'tb-ED',            'Edit name'
+        b 'tb-WI',            'Interrupt'
+        b 'tb-CBP',           'Clear trace/stop/monitor for this object'
+        b 'tb-LN  last',      'Toggle line numbers'
         '<span class="tb-separator"></span>'
         '<input class="tb-search text-field">'
-        b 'tb-NX first',     'Search for next match'
-        b 'tb-PV',           'Search for previous match'
-        b 'tb-case last',    'Match case'
+        b 'tb-NX first',      'Search for next match'
+        b 'tb-PV',            'Search for previous match'
+        b 'tb-case last',     'Match case'
       ].join ''}
     </div>
     <div class="toolbar editor-toolbar">
       #{[
-        b 'tb-EP  last',    'Save changes and return'
+        b 'tb-EP  last',      'Save changes and return'
         b 'tb-pop first',     'Edit in a floating window'
-        b 'tb-LN  first',    'Toggle line numbers'
-        b 'tb-AO',           'Comment selected text'
-        b 'tb-DO  last',     'Uncomment selected text'
+        b 'tb-LN  first',     'Toggle line numbers'
+        b 'tb-AO',            'Comment selected text'
+        b 'tb-DO  last',      'Uncomment selected text'
         '<span class="tb-separator"></span>'
         '<input class="tb-search text-field">'
-        b 'tb-NX  first',    'Search for next match'
-        b 'tb-PV',           'Search for previous match'
-        b 'tb-case last',    'Match case'
+        b 'tb-NX  first',     'Search for next match'
+        b 'tb-PV',            'Search for previous match'
+        b 'tb-case last',     'Match case'
         '<span class="tb-separator"></span>'
-        b 'tb-refac-m first','Refactor text as method'
-        b 'tb-refac-f',      'Refactor text as field'
-        b 'tb-refac-p last', 'Refactor text as property'
+        b 'tb-refac-m first', 'Refactor text as method'
+        b 'tb-refac-f',       'Refactor text as field'
+        b 'tb-refac-p last',  'Refactor text as property'
       ].join ''}
     </div>
     <div class="cm"></div>
   """
   b = null
 
-  volatileLine = null
+  volatileLine = null # the line number of the empty line inserted when cursor is at eof and you press <down>
 
   cm = CodeMirror $e.find('.cm')[0],
     fixedGutter: false, firstLineNumber: 0, lineNumberFormatter: (i) -> "[#{i}]"

  ###

  createBreakpointElement = -> $('<div class="breakpoint">●</div>')[0]
  breakpoints = []
  cm.on 'gutterClick', (cm, l) ->
    if breakpoints.indexOf(l) >= 0 then breakpoints.splice l, 1; cm.setGutterMarker l, 'breakpoints', null
    else breakpoints.push l; cm.setGutterMarker l, 'breakpoints', createBreakpointElement()

    if opener then $('title').text ee.name
    return
  hasFocus: -> cm.hasFocus()
  focus: -> cm.focus(); return
  insert: (ch) -> (if !cm.getOption 'readOnly' then c = cm.getCursor(); cm.replaceRange ch, c, c); return
  getValue: -> cm.getValue()
  getCursorIndex: -> cm.indexFromPos cm.getCursor()
  setValue: (x) -> cm.setValue x; return
  setCursorIndex: (i) -> cm.setCursor cm.posFromIndex i; return
  highlight: highlight
  getHighlightedLine: -> hll
  setDebugger: setDebugger
