some xml-doc

Author: retailcoder

Rubberduck.Core/AutoComplete/AutoCompleteHandlerBase.cs

@@ -5,6 +5,9 @@
 
 namespace Rubberduck.AutoComplete
 {
+    /// <summary>
+    /// A base class/interface for AC services / "handlers".
+    /// </summary>
     public abstract class AutoCompleteHandlerBase
     {
         protected AutoCompleteHandlerBase(ICodePaneHandler pane)
@@ -14,6 +17,13 @@ protected AutoCompleteHandlerBase(ICodePaneHandler pane)
 
         protected ICodePaneHandler CodePaneHandler { get; }
 
+        /// <summary>
+        /// A method that returns <c>false</c> if the input isn't handled, <c>true</c> if it is.
+        /// </summary>
+        /// <param name="e">The autocompletion event info</param>
+        /// <param name="settings">The current AC settings</param>
+        /// <param name="result">If handled, the resulting <c>CodeString</c></param>
+        /// <returns></returns>
         public abstract bool Handle(AutoCompleteEventArgs e, AutoCompleteSettings settings, out CodeString result);
     }
 }

Rubberduck.Core/AutoComplete/AutoCompleteService.cs

@@ -7,6 +7,10 @@
 
 namespace Rubberduck.AutoComplete
 {
+    /// <summary>
+    /// A service responsible for dispatching CodePane work to more specialized autocompletion services.
+    /// Handles changes in configuration settings.
+    /// </summary>
     public class AutoCompleteService : IDisposable
     {
         private static readonly ILogger Logger = LogManager.GetCurrentClassLogger();
@@ -151,6 +155,7 @@ private bool TryHandle(AutoCompleteEventArgs e, AutoCompleteHandlerBase handler)
                     return false;
                 }
 
+                Logger.Debug($"Keypress was handled by {handler.GetType().Name}.");
                 e.Handled = true;
                 return true;
 
@@ -169,7 +174,8 @@ public void Dispose()
         }
 
         private bool _isDisposed;
-        protected virtual void Dispose(bool disposing)
+
+        private void Dispose(bool disposing)
         {
             if (_isDisposed || !disposing)
             {

Rubberduck.Core/AutoComplete/SelfClosingPairs/SelfClosingPairHandler.cs

@@ -7,6 +7,9 @@
 
 namespace Rubberduck.AutoComplete.SelfClosingPairs
 {
+    /// <summary>
+    /// An AC handler that automatically closes certain specific "pairs" of characters, e.g. double quotes, or parentheses.
+    /// </summary>
     public class SelfClosingPairHandler : AutoCompleteHandlerBase
     {
         private const int MaximumLines = 25;
@@ -38,6 +41,7 @@ public override bool Handle(AutoCompleteEventArgs e, AutoCompleteSettings settin
             result = null;
             if (!_scpInputLookup.TryGetValue(e.Character, out var pair) && e.Character != '\b')
             {
+                // not an interesting keypress.
                 return false;
             }
 
@@ -49,15 +53,25 @@ public override bool Handle(AutoCompleteEventArgs e, AutoCompleteSettings settin
                 return false;
             }
 
+            if (!original.CaretPosition.IsSingleCharacter)
+            {
+                // here would be an opportunity to "wrap selection" with a SCP.
+                // todo: WrapSelectionWith(pair)?
+                result = null;
+                return false;
+            }
+
             if (pair != null)
             {
+                // found a SCP for the input key; see if we should handle it:
                 if (!HandleInternal(e, original, pair, out result))
                 {
                     return false;
                 }
             }
             else if (e.Character == '\b')
             {
+                // backspace - see if SCP logic needs to intervene:
                 foreach (var scp in _selfClosingPairs)
                 {
                     if (HandleInternal(e, original, scp, out result))
@@ -69,9 +83,11 @@ public override bool Handle(AutoCompleteEventArgs e, AutoCompleteSettings settin
 
             if (result == null)
             {
+                // no meaningful output; let the input be handled by another handler, maybe.
                 return false;
             }
 
+            // 1-based selection span in the code pane starts at column 1 but really encompasses the entire line.
             var snippetPosition = new Selection(result.SnippetPosition.StartLine, 1, result.SnippetPosition.EndLine, 1);
             result = new CodeString(result.Code, result.CaretPosition, snippetPosition);
 
@@ -81,13 +97,6 @@ public override bool Handle(AutoCompleteEventArgs e, AutoCompleteSettings settin
 
         private bool HandleInternal(AutoCompleteEventArgs e, CodeString original, SelfClosingPair pair, out CodeString result)
         {
-            if (!original.CaretPosition.IsSingleCharacter)
-            {
-                // todo: WrapSelectionWith(pair)?
-                result = null;
-                return false;
-            }
-
             // if executing the SCP against the original code yields no result, we need to bail out.
             if (!_scpService.Execute(pair, original, e.Character, out result))
             {

Rubberduck.VBEEditor/SourceCodeHandling/ISourceCodeHandler.cs

@@ -2,6 +2,9 @@
 
 namespace Rubberduck.VBEditor.SourceCodeHandling
 {
+    /// <summary>
+    /// An object that can rewrite a module's contents.
+    /// </summary>
     public interface ISourceCodeHandler : ISourceCodeProvider
     {
         /// <summary>
@@ -10,6 +13,9 @@ public interface ISourceCodeHandler : ISourceCodeProvider
         void SubstituteCode(QualifiedModuleName module, string newCode);
     }
 
+    /// <summary>
+    /// An object that can manipulate the code in a CodePane.
+    /// </summary>
     public interface ICodePaneHandler : ISourceCodeHandler
     {
         /// <summary>