Make the generic version of SafeIDispatchWrapper visible only to Rubberduck.VBEditor and Rubberduck.VBEditor.* to ensure raw COM objects will not leak outside those projects.

Add comments describing the intended usage of both versions.

Author: bclothier

Rubberduck.VBEEditor/Properties/AssemblyInfo.cs

@@ -1,9 +1,12 @@
-using System.Reflection;
-using System.Runtime.InteropServices;
+using System.Runtime.InteropServices;
 using System.Runtime.CompilerServices;
 
 [assembly: InternalsVisibleTo("RubberduckTests")]
 
+//Allow Rubberduck.VBEditor.* projects to use internal class
+[assembly: InternalsVisibleTo("Rubberduck.VBEditor.VB6")]
+[assembly: InternalsVisibleTo("Rubberduck.VBEditor.VBA")]
+
 // The following GUID is for the ID of the typelib if this project is exposed to COM
 [assembly: Guid("4758424b-266e-4a3a-83c6-4aa50af7ea9e")]
 [assembly: ComVisible(false)]

Rubberduck.VBEEditor/SafeComWrappers/SafeIDispatchWrapper.cs

@@ -4,14 +4,36 @@
 
 namespace Rubberduck.VBEditor.SafeComWrappers
 {
-    public class SafeIDispatchWrapper<TDispatch> : SafeIDispatchWrapper
+    /// <summary>
+    /// Creates a new IDispatch-based wrapper for a provided
+    /// COM interface. This is internal and should be used only
+    /// within the Rubberduck.VBEditor.* projects.
+    /// </summary>
+    /// <remarks>
+    /// To avoid exposing additional interop libraries to other projects
+    /// and violating the separation, only the non-generic version of
+    /// <see cref="SafeIDispatchWrapper" /> be provided for consumption outside
+    /// the Rubberduck.VBEditor.* projects.
+    /// Within those projects, the class is useful for wrapping COM interfaces
+    /// that do not have a corresponding  <see cref="ISafeComWrapper{T}" />
+    /// implementations to ensure those are managed and will not leak.
+    /// </remarks>
+    /// <typeparam name="TDispatch">COM interface to wrap</typeparam>
+    /// <inheritdoc />
+    internal class SafeIDispatchWrapper<TDispatch> : SafeIDispatchWrapper
     {
-        public SafeIDispatchWrapper(TDispatch target, bool rewrapping = false) : base(target, rewrapping)
+        internal SafeIDispatchWrapper(TDispatch target, bool rewrapping = false) : base(target, rewrapping)
         { }
 
         public new TDispatch Target => (TDispatch) base.Target;
     }
 
+    /// <summary>
+    /// Provide a IDispatch-based (e.g. late-bound) access to a COM object.
+    /// Use <see cref="Invoke"/> to work with the object. The
+    /// <see cref="SafeIDispatchWrapper.Target"/> must be a raw COM object without
+    /// any wrappers. 
+    /// </summary>
     public class SafeIDispatchWrapper : SafeComWrapper<dynamic>
     {
         public SafeIDispatchWrapper(object target, bool rewrapping = false) : base(target, rewrapping)
@@ -24,8 +46,18 @@ public SafeIDispatchWrapper(object target, bool rewrapping = false) : base(targe
             IDispatchPointer = GetPointer(target);
         }
 
+        // ReSharper disable once InconsistentNaming
         public IntPtr IDispatchPointer { get; }
 
+        /// <summary>
+        /// Use the method to encapsulate operations against the late-bound COM object.
+        /// It is caller's responsibilty to handle any exceptions that may result as part
+        /// of the operation. 
+        /// </summary>
+        /// <param name="action">
+        /// A method that perform work against the late-bound COM object provided as the
+        /// parameter to the function
+        /// </param>
         public void Invoke(Action<dynamic> action)
         {
             action.Invoke(Target);