Add comments to editor.js

src/app/editor/editor.js

@@ -95,11 +95,7 @@ class Editor {
   */
 
   constructor(opts = {}, localRegistry) {
-    const el = yo`<div id="input"></div>`
-    this.editor = ace.edit(el)
-    if (styles.appProperties.aceTheme) {
-      this.editor.setTheme('ace/theme/' + styles.appProperties.aceTheme)
-    }
+    // Dependancies
     this._components = {}
     this._components.registry = localRegistry || globalRegistry
     this._deps = {
@@ -107,26 +103,14 @@ class Editor {
       config: this._components.registry.get('config').api
     }
 
-    ace.acequire('ace/ext/language_tools')
-    this.editor.setOptions({
-      enableBasicAutocompletion: true,
-      enableLiveAutocompletion: true
-    })
-    const flowCompleter = {
-      getCompletions: function(editor, session, pos, prefix, callback) {
-        // @TODO add here other propositions
-      }
-    }
-    langTools.addCompleter(flowCompleter)
-    el.className += ' ' + css['ace-editor']
-    el.editor = this.editor // required to access the editor during tests
-    this.render = () => el
-
+    // Init
     this.event = new EventManager()
     this.sessions = {}
     this.sourceAnnotations = []
     this.readOnlySessions = {}
-
+    this.previousInput = ''
+    this.saveTimeout = null
+    this.sourceHighlighters = new SourceHighlighters()
     this.emptySession = this._createSession('')
     this.modes = {
       sol: 'ace/mode/solidity',
@@ -138,7 +122,40 @@ class Editor {
       abi: 'ace/mode/json'
     }
 
-    /** Listen on Gutter Mouse Down */
+    // Editor Setup
+    const el = yo`<div id="input"></div>`
+    this.editor = ace.edit(el)
+    ace.acequire('ace/ext/language_tools')
+
+    // Unmap ctrl-t & ctrl-f
+    this.editor.commands.bindKeys({ 'ctrl-t': null })
+    this.editor.setShowPrintMargin(false)
+    this.editor.resize(true)
+
+    if (styles.appProperties.aceTheme) {
+      this.editor.setTheme('ace/theme/' + styles.appProperties.aceTheme)
+    }
+
+    this.editor.setOptions({
+      enableBasicAutocompletion: true,
+      enableLiveAutocompletion: true
+    })
+
+    el.className += ' ' + css['ace-editor']
+    el.editor = this.editor // required to access the editor during tests
+    this.render = () => el
+
+    // Completer for editor
+    const flowCompleter = {
+      getCompletions: (editor, session, pos, prefix, callback) => {
+        // @TODO add here other propositions
+      }
+    }
+    langTools.addCompleter(flowCompleter)
+
+    // EVENTS LISTENERS
+
+    // Gutter Mouse down
     this.editor.on('guttermousedown', e => {
       const target = e.domEvent.target
       if (target.className.indexOf('ace_gutter-cell') === -1) {
@@ -159,8 +176,6 @@ class Editor {
       e.stop()
     })
 
-    this.previousInput = ''
-    this.saveTimeout = null
     // Do setup on initialisation here
     this.editor.on('changeSession', () => {
       this._onChange()
@@ -171,13 +186,6 @@ class Editor {
         this.event.trigger('contentChanged', [])
       })
     })
-
-    // Unmap ctrl-t & ctrl-f
-    this.editor.commands.bindKeys({ 'ctrl-t': null })
-    this.editor.setShowPrintMargin(false)
-    this.editor.resize(true)
-
-    this.sourceHighlighters = new SourceHighlighters()
   }
 
   _onChange() {
@@ -212,12 +220,21 @@ class Editor {
     this.editor.focus()
   }
 
+  /**
+   * Get Ace mode base of the extension of the session file
+   * @param {string} path Path of the file
+   */
   _getMode(path) {
     let ext = path.indexOf('.') !== -1 ? /[^.]+$/.exec(path) : null
     if (ext) ext = ext[0]
     return ext && this.modes[ext] ? this.modes[ext] : this.modes['txt']
   }
 
+  /**
+   * Create an Ace session
+   * @param {string} content Content of the file to open
+   * @param {string} mode Ace Mode for this file [Default is `text`]
+   */
   _createSession(content, mode) {
     const s = new ace.EditSession(content)
     s.setMode(mode || 'ace/mode/text')
@@ -227,30 +244,55 @@ class Editor {
     return s
   }
 
+  /**
+   * Attempts to find the string in the current document
+   * @param {string} string
+   */
   find(string) {
     return this.editor.find(string)
   }
 
+  /**
+   * Display an Empty read-only session
+   */
   displayEmptyReadOnlySession() {
     this.currentSession = null
     this.editor.setSession(this.emptySession)
     this.editor.setReadOnly(true)
   }
 
-  setBreakpoint(row, css) {
-    this.editor.session.setBreakpoint(row, css)
+  /**
+   * Sets a breakpoint on the row number
+   * @param {number} row Line index of the breakpoint
+   * @param {string} className Class of the breakpoint
+   */
+  setBreakpoint(row, className) {
+    this.editor.session.setBreakpoint(row, className)
   }
 
+  /**
+   * Increment the font size (in pixels) for the editor text.
+   * @param {number} incr The amount of pixels to add to the font.
+   */
   editorFontSize(incr) {
     this.editor.setFontSize(this.editor.getFontSize() + incr)
   }
 
+  /**
+   * Set the text in the current session, if any.
+   * @param {string} text New text to be place.
+   */
   setText(text) {
     if (this.currentSession && this.sessions[this.currentSession]) {
       this.sessions[this.currentSession].setValue(text)
     }
   }
 
+  /**
+   * Upsert and open a session.
+   * @param {string} path Path of the session to open.
+   * @param {string} content Content of the document or update.
+   */
   open(path, content) {
     if (!this.sessions[path]) {
       const session = this._createSession(content, this._getMode(path))
@@ -262,6 +304,11 @@ class Editor {
     this._switchSession(path)
   }
 
+  /**
+   * Upsert and Open a session and set it as Read-only.
+   * @param {string} path Path of the session to open.
+   * @param {string} content Content of the document or update.
+   */
   openReadOnly(path, content) {
     if (!this.sessions[path]) {
       const session = this._createSession(content, this._getMode(path))
@@ -272,8 +319,7 @@ class Editor {
   }
 
   /**
-   * returns the content of the current session
-   *
+   * Content of the current session
    * @return {String} content of the file referenced by @arg path
    */
   currentContent() {
@@ -281,9 +327,9 @@ class Editor {
   }
 
   /**
-   * returns the content of the session targeted by @arg path
+   * Content of the session targeted by @arg path
    * if @arg path is null, the content of the current session is returned
-   *
+   * @param {string} path Path of the session to get.
    * @return {String} content of the file referenced by @arg path
    */
   get(path) {
@@ -295,9 +341,8 @@ class Editor {
   }
 
   /**
-   * returns the path of the currently editing file
+   * Path of the currently editing file
    * returns `undefined` if no session is being editer
-   *
    * @return {String} path of the current session
    */
   current() {
@@ -307,6 +352,9 @@ class Editor {
     return this.currentSession
   }
 
+  /**
+   * The position of the cursor
+   */
   getCursorPosition() {
     return this.editor.session.doc.positionToIndex(
       this.editor.getCursorPosition(),
@@ -314,6 +362,9 @@ class Editor {
     )
   }
 
+  /**
+   * Remove the current session from the list of sessions.
+   */
   discardCurrentSession() {
     if (this.sessions[this.currentSession]) {
       delete this.sessions[this.currentSession]
@@ -321,11 +372,19 @@ class Editor {
     }
   }
 
+  /**
+   * Remove a session based on its path.
+   * @param {string} path
+   */
   discard(path) {
     if (this.sessions[path]) delete this.sessions[path]
     if (this.currentSession === path) this.currentSession = null
   }
 
+  /**
+   * Resize the editor, and sets whether or not line wrapping is enabled.
+   * @param {boolean} useWrapMode Enable (or disable) wrap mode
+   */
   resize(useWrapMode) {
     this.editor.resize()
     const session = this.editor.getSession()
@@ -342,6 +401,12 @@ class Editor {
     }
   }
 
+  /**
+   * Adds a new marker to the given `Range`.
+   * @param {*} lineColumnPos
+   * @param {string} source Path of the session to add the mark on.
+   * @param {string} cssClass css to apply to the mark.
+   */
   addMarker(lineColumnPos, source, cssClass) {
     const currentRange = new Range(
       lineColumnPos.start.line,
@@ -355,30 +420,58 @@ class Editor {
     return null
   }
 
+  /**
+   * Scrolls to a line. If center is true, it puts the line in middle of screen (or attempts to).
+   * @param {number} line The line to scroll to
+   * @param {boolean} center If true
+   * @param {boolean} animate If true animates scrolling
+   * @param {Function} callback Function to be called when the animation has finished
+   */
   scrollToLine(line, center, animate, callback) {
     this.editor.scrollToLine(line, center, animate, callback)
   }
 
+  /**
+   * Remove a marker from the session
+   * @param {string} markerId Id of the marker
+   * @param {string} source Path of the session
+   */
   removeMarker(markerId, source) {
     if (this.sessions[source]) {
       this.sessions[source].removeMarker(markerId)
     }
   }
 
+  /**
+   * Clears all the annotations for the current session.
+   */
   clearAnnotations() {
     this.sourceAnnotations = []
     this.editor.getSession().clearAnnotations()
   }
 
+  /**
+   * Add an annotation to the current session.
+   * @param {Object} annotation
+   */
   addAnnotation(annotation) {
     this.sourceAnnotations[this.sourceAnnotations.length] = annotation
     this.setAnnotations(this.sourceAnnotations)
   }
 
+  /**
+   * Set a list of annotations to the current session.
+   * @param {Array<Object>} annotation
+   */
   setAnnotations(sourceAnnotations) {
     this.editor.getSession().setAnnotations(sourceAnnotations)
   }
 
+  /**
+   * Moves the cursor and focus to the specified line and column number
+   * @param {number} line
+   * @param {number} col
+   */
   gotoLine(line, col) {
     this.editor.focus()
     this.editor.gotoLine(line + 1, col - 1, true)