Monday is code tedium day: commenting the editor

lib/gollum/frontend/public/javascript/gollum-editor/gollum.editor.js

@@ -269,10 +269,26 @@
                $('#gollum-editor-body').length );
     },
     
+    
+    /**
+     *  EditorHas.collapsibleInputs
+     *  True if the editor contains collapsible inputs for things like the 
+     *  sidebar or footer, false otherwise.
+     *
+     *  @return boolean
+     */
     collapsibleInputs: function() {
       return $('#gollum-editor .collapsed, #gollum-editor .expanded').length;
     },
     
+    
+    /**
+     *  EditorHas.formatSelector
+     *  True if the editor has a format selector (for switching between 
+     *  language types), false otherwise.
+     *
+     *  @return boolean
+     */
     formatSelector: function() {
       return $('#gollum-editor-format-selector select').length;
     },
@@ -301,24 +317,60 @@
       return ( ua.test( navigator.userAgent ) );
     },
     
+    
+    /**
+     *  EditorHas.editSummaryMarkup
+     *  True if the editor has a summary field (Gollum's commit message), 
+     *  false otherwise.
+     *
+     *  @return boolean
+     */
     editSummaryMarkup: function() {
       return ( $('input#gollum-editor-message-field').length > 0 );
     },
     
+    
+    /**
+     *  EditorHas.help
+     *  True if the editor contains the inline help sector, false otherwise.
+     *
+     *  @return boolean
+     */
     help: function() {
       return ( $('#gollum-editor #gollum-editor-help').length && 
                $('#gollum-editor #function-help').length );
     },
     
+    
+    /**
+     *  EditorHas.mathJax
+     *  True if the editor has MathJax enabled and running, false otherwise.
+     *
+     *  @return boolean
+     */
     mathJax: function() {
       //TODO
       return false;
     },
     
+    
+    /**
+     *  EditorHas.previewButton
+     *  True if the editor has a preview button, false otherwise.
+     *
+     *  @return boolean
+     */
     previewButton: function() {
       return ( $('#gollum-editor #gollum-editor-preview').length );
     },
     
+    
+    /**
+     *  EditorHas.titleDisplayed
+     *  True if the editor is displaying a title field, false otherwise.
+     *
+     *  @return boolean
+     */
     titleDisplayed: function() {
       return ( ActiveOptions.NewFile );
     }
@@ -504,15 +556,36 @@
    };
 
 
+   
+   /**
+    *  FormatSelector
+    *
+    *  Functions relating to the format selector (if it exists)
+    */
    var FormatSelector = {
      
      $_SELECTOR: null,
      
+     /**
+      *  FormatSelector.evtChangeFormat
+      *  Event handler for when a format has been changed by the format 
+      *  selector. Will automatically load a new language definition 
+      *  via JS if necessary.
+      *
+      *  @return void
+      */
      evtChangeFormat: function( e ) {
        var newMarkup = $(this).val();
        LanguageDefinition.setActiveLanguage( newMarkup );
      },
      
+     
+     /**
+      *  FormatSelector.init
+      *  Initializes the format selector.
+      *
+      *  @return void
+      */
      init: function( $sel ) {
        debug('Initializing format selector');
        
@@ -528,12 +601,30 @@
    
    
    
+   /**
+    *  Help
+    * 
+    *  Functions that manage the display and loading of inline help files. 
+    */
   var Help = {
      
     _ACTIVE_HELP: '',
    _LOADED_HELP_LANGS: [],
    _HELP: {},
    
+   
+   /**
+    *  Help.define 
+    *
+    *  Defines a new help context and enables the help function if it 
+    *  exists in the Gollum Function Bar.
+    *
+    *  @param string name   The name you're giving to this help context. 
+    *                       Generally, this should match the language name.
+    *  @param object definitionObject The definition object being loaded from a 
+    *                                 language / help definition file.
+    *  @return void
+    */
    define: function( name, definitionObject ) {       
      if ( Help.isValidHelpFormat( definitionObject ) ) {
        debug('help is a valid format');
@@ -559,6 +650,14 @@
      }
    },
    
+   
+   /**
+    *  Help.generateHelpMenuFor
+    *  Generates the markup for the main help menu given a context name.
+    *  
+    *  @param string  name  The context name. 
+    *  @return void
+    */
    generateHelpMenuFor: function( name ) {
      if ( !Help._HELP[name] ) {
        debug('Help is not defined for ' + name.toString());
@@ -598,6 +697,16 @@
      
    },
    
+   
+   /**
+    *  Help.generateSubMenu
+    *  Generates the markup for the inline help sub-menu given the data 
+    *  object for the submenu and the array index to start at.
+    *
+    *  @param object subData The data for the sub-menu.
+    *  @param integer index  The index clicked on (parent menu index).
+    *  @return void
+    */
    generateSubMenu: function( subData, index ) {
      $('#gollum-editor-help-list').html('');
      $('#gollum-editor-help-content').html('');
@@ -613,12 +722,31 @@
      }
    },
    
+   
+   /**
+    *  Help.showHelpFor
+    *  Displays the actual help content given the two menu indexes, which are 
+    *  rendered in the rel="" attributes of the help menus
+    *
+    *  @param integer index1  parent index
+    *  @param integer index2  submenu index
+    *  @return void
+    */
    showHelpFor: function( index1, index2 ) {
      var html =
        Help._HELP[Help._ACTIVE_HELP_LANG][index1].content[index2].data;
      $('#gollum-editor-help-content').html(html);
    },
    
+   
+   /**
+    *  Help.isLoadedFor
+    *  Returns true if help is loaded for a specific markup language, 
+    *  false otherwise.
+    *
+    *  @param string name   The name of the markup language.
+    *  @return boolean
+    */
    isLoadedFor: function( name ) {
      for ( var i=0; i < Help._LOADED_HELP_LANGS.length; i++ ) {
        if ( name == Help._LOADED_HELP_LANGS[i] ) {
@@ -628,6 +756,15 @@
      return false;
    },
    
+   
+   /**
+    *  Help.isValidHelpFormat
+    *  Does a quick check to make sure that the help definition isn't in a 
+    *  completely messed-up format. 
+    *
+    *  @param object (Array) helpArr  The help definition array.
+    *  @return boolean
+    */
    isValidHelpFormat: function( helpArr ) {
      return ( typeof helpArr == 'object' &&
               helpArr.length &&
@@ -636,6 +773,15 @@
               helpArr[0].content.length );
    },
    
+   
+   /**
+    *  Help.setActiveHelp
+    *  Sets the active help definition to the one defined in the argument, 
+    *  re-rendering the help menu to match the new definition.
+    *
+    *  @param string  name  The name of the help definition.
+    *  @return void
+    */
    setActiveHelp: function( name ) {
      if ( !Help.isLoadedFor( name ) ) {
        if ( $('#function-help').length ) {
@@ -654,6 +800,14 @@
      }
    },
    
+   
+   /**
+    *  Help.evtHelpButtonClick
+    *  Event handler for clicking the help button in the function bar.
+    *
+    *  @param jQuery.Event e  The jQuery event object.
+    *  @return void
+    */
    evtHelpButtonClick: function( e ) {
      e.preventDefault();
      
@@ -677,6 +831,16 @@
      }
    },
    
+   
+   /**
+    *  Help.evtParentMenuClick
+    *  Event handler for clicking on an item in the parent menu. Automatically 
+    *  renders the submenu for the parent menu as well as the first result for 
+    *  the actual plain text.
+    *
+    *  @param jQuery.Event e  The jQuery event object.
+    *  @return void
+    */
    evtParentMenuClick: function( e ) {
      e.preventDefault();
      // short circuit if we've selected this already
@@ -692,6 +856,15 @@
      $($('#gollum-editor-help-list li a').get(0)).click();
    },
    
+   
+   /**
+    *  Help.evtSubMenuClick
+    *  Event handler for clicking an item in a help submenu. Renders the 
+    *  appropriate text for the submenu link.
+    *
+    *  @param jQuery.Event e  The jQuery event object.
+    *  @return void 
+    */
    evtSubMenuClick: function( e ) {
      e.preventDefault();
      if ( $(this).hasClass('selected') ) return;
@@ -702,23 +875,19 @@
      $(this).addClass('selected');
      Help.showHelpFor( rawIndex[0], rawIndex[1] );
    }
-     
  };
    
    
-   /**
+   // Publicly-accessible function to Help.define
-    *  $.GollumEditor.Dialog
-    *  Used in exec() to display dialogs with dynamic fields.
-    *
-    */
    $.GollumEditor.defineHelp = Help.define;
    
-   // Dialog is separate too
+   // Dialog exists as its own thing now
    $.GollumEditor.Dialog = $.GollumDialog;
    $.GollumEditor.replaceSelection = function( repText ) {
      FunctionBar.replaceFieldSelection( $('#gollum-editor-body'), repText );
    }
    
+   // Placeholder exists as its own thing now
    $.GollumEditor.Placeholder = $.GollumPlaceholder;
   
 })(jQuery);