Final run through of documentation updates.

bclothier · bclothier · commit f606675a9ee8 · 2019-08-04T08:09:21.000-05:00
diff --git a/Rubberduck.CodeAnalysis/Rubberduck.CodeAnalysis.xml b/Rubberduck.CodeAnalysis/Rubberduck.CodeAnalysis.xml
diff --git a/Rubberduck.VBEEditor/ComManagement/TypeLibs/Public/TypeLibWrapperProvider.cs b/Rubberduck.VBEEditor/ComManagement/TypeLibs/Public/TypeLibWrapperProvider.cs
@@ -1,4 +1,5 @@
-﻿using Rubberduck.VBEditor.ComManagement.TypeLibs.Abstract;
+﻿using System.Runtime.InteropServices.ComTypes;
+using Rubberduck.VBEditor.ComManagement.TypeLibs.Abstract;
 using Rubberduck.VBEditor.SafeComWrappers.Abstract;
 
 // ReSharper disable once CheckNamespace
@@ -8,6 +9,14 @@ public class TypeLibWrapperProvider : ITypeLibWrapperProvider
     {
         private readonly IProjectsProvider _projectsProvider;
 
+        /// <summary>
+        /// Simplifies the work of obtaining a <see cref="ITypeLib"/> for a given
+        /// <see cref="IVBProject"/> and wraps in a <see cref="ITypeLibWrapper"/>
+        /// in order to expose some VBE-specific extensions upon the type APIs.
+        /// </summary>
+        /// <param name="projectsProvider">
+        /// Injected provider maintaining a collection of <see cref="IVBProject"/>s
+        /// </param>
         public TypeLibWrapperProvider(IProjectsProvider projectsProvider)
         {
             _projectsProvider = projectsProvider;
diff --git a/Rubberduck.VBEEditor/ComManagement/TypeLibs/TypeInfoFunction.cs b/Rubberduck.VBEEditor/ComManagement/TypeLibs/TypeInfoFunction.cs
@@ -6,7 +6,8 @@
 namespace Rubberduck.VBEditor.ComManagement.TypeLibs
 {
     /// <summary>
-    /// A class that represents a function definition within a <see cref="ComTypes.ITypeInfo"/>.  Essentially a wrapper for <see cref="ComTypes.FUNCDESC"/>.
+    /// A class that represents a function definition described in <see cref="ComTypes.FUNCDESC"/>
+    /// within a <see cref="ComTypes.ITypeInfo"/>.  
     /// </summary>
     internal class TypeInfoFunction : ITypeInfoFunction
     {
diff --git a/Rubberduck.VBEEditor/ComManagement/TypeLibs/TypeInfoVariable.cs b/Rubberduck.VBEEditor/ComManagement/TypeLibs/TypeInfoVariable.cs
@@ -6,7 +6,8 @@
 namespace Rubberduck.VBEditor.ComManagement.TypeLibs
 {
     /// <summary>
-    /// A class that represents a variable or field within a <see cref="ComTypes.ITypeInfo"/>
+    /// A class that represents a variable or field described in a <see cref="ComTypes.VARDESC"/>
+    /// within a <see cref="ComTypes.ITypeInfo"/>
     /// </summary>
     internal class TypeInfoVariable : ITypeInfoVariable
     {
diff --git a/Rubberduck.VBEEditor/ComManagement/TypeLibs/TypeInfoWrapper.cs b/Rubberduck.VBEEditor/ComManagement/TypeLibs/TypeInfoWrapper.cs
@@ -42,6 +42,19 @@ public enum TYPEKIND_VBE
     ///     so there will be little bugs.  This bug is also resolved in the provided wrappers.
     ///
     /// This class can also be cast to <see cref="ComTypes.ITypeInfo"/> for safe access to the underlying type information
+    ///
+    /// TypeInfos from a VBA hosted project, and obtained through <see cref="VBETypeLibsAccessor"/> will have the following behaviours:
+    /// 
+    ///   will expose both public and private procedures and fields
+    ///   will expose constants values, but they are unnamed (their member IDs will be MEMBERID_NIL)
+    ///   module level variables in a standard module are hidden (ref to <see cref="TypeInfoConstantsCollection"/> for details)
+    ///   enumerations are not exposed directly in the type library
+    ///   enumerations may be referenced by field/argument datatypes, and the ITypeInfos for them are then accessible that way
+    ///   UDTs are not exposed directly in the type library
+    ///   UDTs may be referenced by field/argument datatypes, and as such the ITypeInfos for them are then accessible that way
+    ///   
+    /// TypeInfos obtained by other means (such as the IDispatch::GetTypeInfo method) usually expose more restricted
+    /// versions of ITypeInfo which may not expose private members
     /// </remarks>
     internal sealed class TypeInfoWrapper : TypeInfoInternalSelfMarshalForwarderBase, ITypeInfoWrapper
     {
diff --git a/Rubberduck.VBEEditor/ComManagement/TypeLibs/TypeInfoWrapperCollection.cs b/Rubberduck.VBEEditor/ComManagement/TypeLibs/TypeInfoWrapperCollection.cs
@@ -5,23 +5,6 @@
 using Rubberduck.VBEditor.ComManagement.TypeLibs.Unmanaged;
 using Rubberduck.VBEditor.ComManagement.TypeLibs.Utility;
 
-/// <summary>
-/// For usage examples, please see VBETypeLibsAPI
-/// </summary>
-/// <remarks>
-/// TypeInfos from a VBA hosted project, and obtained through VBETypeLibsAccessor will have the following behaviours:
-/// 
-///   will expose both public and private prcoedures and fields
-///   will expose constants values, but they are unnamed (their member IDs will be MEMBERID_NIL)
-///   enumerations are not exposed directly in the type library
-///   enumerations may be referenced by field/argument datatypes, and the ITypeInfos for them are then accessible that way
-///   UDTs are not exposed directly in the type library
-///   UDTs may be referenced by field/argument datatypes, and as such the ITypeInfos for them are then accessible that way
-///   
-/// TypeInfos obtained by other means (such as the IDispatch::GetTypeInfo method) usually expose more restricted
-/// versions of ITypeInfo which may not expose private members
-/// </remarks>
-
 namespace Rubberduck.VBEditor.ComManagement.TypeLibs
 {
     /// <summary>
diff --git a/Rubberduck.VBEEditor/ComManagement/TypeLibs/Unmanaged/AddressableVariables.cs b/Rubberduck.VBEEditor/ComManagement/TypeLibs/Unmanaged/AddressableVariables.cs
@@ -3,7 +3,7 @@
 namespace Rubberduck.VBEditor.ComManagement.TypeLibs.Unmanaged
 {
     /// <summary>
-    /// AddressableVariables aid creating and handling unmanaged data
+    /// AddressableVariables aids in creating and handling unmanaged data
     /// </summary>
     /// <remarks>
     /// AddressableVariables are created in unmanaged memory space, designed to aid creating addressable
diff --git a/Rubberduck.VBEEditor/ComManagement/TypeLibs/Unmanaged/ComHelper.cs b/Rubberduck.VBEEditor/ComManagement/TypeLibs/Unmanaged/ComHelper.cs
@@ -128,7 +128,7 @@ internal static class ComHelper
         public static bool DoesComObjPtrSupportInterface<T>(IntPtr comObjPtr)
         {
             var iid = typeof(T).GUID;
-            int hr = RdMarshal.QueryInterface(comObjPtr, ref iid, out var outInterfacePtr);
+            var hr = RdMarshal.QueryInterface(comObjPtr, ref iid, out var outInterfacePtr);
             if (!ComHelper.HRESULT_FAILED(hr))
             {
                 RdMarshal.Release(outInterfacePtr);
diff --git a/Rubberduck.VBEEditor/ComManagement/TypeLibs/Unmanaged/IDispatchHelper.cs b/Rubberduck.VBEEditor/ComManagement/TypeLibs/Unmanaged/IDispatchHelper.cs
@@ -6,7 +6,8 @@
 namespace Rubberduck.VBEditor.ComManagement.TypeLibs.Unmanaged
 {
     /// <summary>
-    /// Used by methods in the ITypeInfo and ITypeLib interfaces.  Usually used to get the root type or library name.
+    /// Used by methods in the <see cref="ComTypes.ITypeInfo"/> and <see cref="ComTypes.ITypeLib"/> interfaces.
+    /// Usually used to get the root type or library name.
     /// </summary>
     internal enum KnownDispatchMemberIDs 
     {
@@ -52,7 +53,7 @@ public enum InvokeKind : int
         /// see https://msdn.microsoft.com/en-us/library/windows/desktop/ms221416(v=vs.85).aspx
         /// </summary>
         /// <param name="args">An array of arguments to wrap</param>
-        /// <returns>DISPPARAMS structure ready to pass to IDispatch::Invoke</returns>
+        /// <returns><see cref="ComTypes.DISPPARAMS"/> structure ready to pass to IDispatch::Invoke</returns>
         private static ComTypes.DISPPARAMS PrepareDispatchArgs(object[] args)
         {
             var pDispParams = new ComTypes.DISPPARAMS();
@@ -66,7 +67,7 @@ private static ComTypes.DISPPARAMS PrepareDispatchArgs(object[] args)
                 var variantArgsArray = RdMarshal.AllocHGlobal(argsVariantLength);
 
                 // In IDispatch::Invoke, arguments are passed in reverse order
-                IntPtr variantArgsArrayOffset = variantArgsArray + argsVariantLength;
+                var variantArgsArrayOffset = variantArgsArray + argsVariantLength;
                 foreach (var arg in args)
                 {
                     variantArgsArrayOffset -= variantStructSize;
@@ -78,7 +79,7 @@ private static ComTypes.DISPPARAMS PrepareDispatchArgs(object[] args)
         }
 
         [DllImport("oleaut32.dll", SetLastError = true, CallingConvention = CallingConvention.StdCall)]
-        static extern Int32 VariantClear(IntPtr pvarg);
+        static extern int VariantClear(IntPtr pvarg);
 
         /// <summary>
         /// frees all unmanaged memory assoicated with a DISPPARAMS structure
@@ -92,7 +93,7 @@ private static void UnprepareDispatchArgs(ComTypes.DISPPARAMS pDispParams)
                 // free the array of COM VARIANTs
                 var variantStructSize = RdMarshal.SizeOf(typeof(VARIANT));
                 var variantArgsArrayOffset = pDispParams.rgvarg;
-                int argIndex = 0;
+                var argIndex = 0;
                 while (argIndex < pDispParams.cArgs)
                 {
                     VariantClear(variantArgsArrayOffset);
@@ -117,8 +118,8 @@ public static object Invoke(IDispatch obj, int memberId, InvokeKind invokeKind,
             var pDispParams = PrepareDispatchArgs(args);
             var pExcepInfo = new ComTypes.EXCEPINFO();
 
-            int hr = obj.Invoke(memberId, ref _guid_null, 0, (uint)invokeKind,
-                                    ref pDispParams, out object pVarResult, ref pExcepInfo, out uint pErrArg);
+            var hr = obj.Invoke(memberId, ref _guid_null, 0, (uint)invokeKind,
+                                    ref pDispParams, out var pVarResult, ref pExcepInfo, out var pErrArg);
 
             UnprepareDispatchArgs(pDispParams);
 
diff --git a/Rubberduck.VBEEditor/ComManagement/TypeLibs/Unmanaged/TypeInfoInternalSelfMarshalForwarderBase.cs b/Rubberduck.VBEEditor/ComManagement/TypeLibs/Unmanaged/TypeInfoInternalSelfMarshalForwarderBase.cs
@@ -5,7 +5,7 @@
 namespace Rubberduck.VBEditor.ComManagement.TypeLibs.Unmanaged
 {
     /// <summary>
-    /// This class marshals ComTypes.ITypeInfo members to ITypeInfoInternal
+    /// This class marshals <see cref="ComTypes.ITypeInfo"/> members to <see cref="ITypeInfoInternal"/>
     /// </summary>
     /// <remarks>
     /// ITypeInfoInternal must be inherited BEFORE ComTypes.ITypeInfo as they both have the same IID 
diff --git a/Rubberduck.VBEEditor/ComManagement/TypeLibs/Unmanaged/TypeLibInternalSelfMarshalForwarderBase.cs b/Rubberduck.VBEEditor/ComManagement/TypeLibs/Unmanaged/TypeLibInternalSelfMarshalForwarderBase.cs
@@ -5,7 +5,7 @@
 namespace Rubberduck.VBEditor.ComManagement.TypeLibs.Unmanaged
 {
     /// <summary>
-    /// A compatible version of ComTypes.ITypeLib, using IntPtr for all out params
+    /// A compatible version of <see cref="ComTypes.ITypeLib"/>, using <see cref="IntPtr"/> for all out params
     /// see https://msdn.microsoft.com/en-us/library/windows/desktop/ms221549(v=vs.85).aspx
     /// </summary>
     /// <remarks>
@@ -28,7 +28,7 @@ internal interface ITypeLibInternal
     }
 
     /// <summary>
-    /// This class marshals ComTypes.ITypeLib members to ITypeLibInternal
+    /// This class marshals <see cref="ComTypes.ITypeLib"/> members to <see cref="ITypeLibInternal"/>
     /// </summary>
     /// <remarks>
     /// ITypeLibInternal must be inherited BEFORE ComTypes.ITypeLib as they both have the same IID 
diff --git a/Rubberduck.VBEEditor/ComManagement/TypeLibs/Unmanaged/UnmanagedMemoryHelper.cs b/Rubberduck.VBEEditor/ComManagement/TypeLibs/Unmanaged/UnmanagedMemoryHelper.cs
@@ -57,12 +57,12 @@ public static bool ValidateComObject(IntPtr comObjectPtr)
             // Is it a valid memory address, with at least one accessible vTable ptr
             if (!IsValidMemoryRange(comObjectPtr, IntPtr.Size)) return false;
 
-            IntPtr vTablePtr = RdMarshal.ReadIntPtr(comObjectPtr);
+            var vTablePtr = RdMarshal.ReadIntPtr(comObjectPtr);
 
             // And for a COM object, we need a valid vtable, with at least 3 vTable entries (for IUnknown)
             if (!IsValidMemoryRange(vTablePtr, IntPtr.Size * 3)) return false;
 
-            IntPtr firstvTableEntry = RdMarshal.ReadIntPtr(vTablePtr);
+            var firstvTableEntry = RdMarshal.ReadIntPtr(vTablePtr);
 
             // And lets check the first vTable entry actually points to EXECUTABLE memory
             // (we could check all 3 initial IUnknown entries, but we want to be reasonably  
@@ -156,9 +156,9 @@ public static T ReadComObjectStructure<T>(object comObj)
         /// Takes an unmanaged memory address and reads the unmanaged memory given by its pointer
         /// </summary>
         /// <typeparam name="T">the type of structure to return</typeparam>
-        /// <param name="memAddress">the unamanaged memory address to read</param>
+        /// <param name="memAddress">the unmanaged memory address to read</param>
         /// <returns>the requested structure T</returns>
-        /// <remarks>use this over ReadStructureSafe for effiency when there is no doubt about the validity of the pointed to data</remarks>
+        /// <remarks>use this over ReadStructureSafe for efficiency when there is no doubt about the validity of the pointed to data</remarks>
         public static T ReadStructureUnsafe<T>(IntPtr memAddress)
         {
             // We catch the most basic mistake of passing a null pointer here as it virtually costs nothing to check, 
diff --git a/Rubberduck.VBEEditor/ComManagement/TypeLibs/Unmanaged/VBETypeLibsIterator.cs b/Rubberduck.VBEEditor/ComManagement/TypeLibs/Unmanaged/VBETypeLibsIterator.cs
@@ -2,12 +2,13 @@
 using System.Collections;
 using System.Collections.Generic;
 using System.Runtime.InteropServices;
+using System.Runtime.InteropServices.ComTypes;
 using Rubberduck.VBEditor.ComManagement.TypeLibs.Abstract;
 
 namespace Rubberduck.VBEditor.ComManagement.TypeLibs.Unmanaged
 {
     /// <summary>
-    /// An internal representation of the ITypeLib object hosted by the VBE.
+    /// An internal representation of the <see cref="ITypeLib"/> object hosted by the VBE.
     /// Also provides Prev/Next pointers, exposing a double linked list of all loaded project ITypeLibs
     /// </summary>
     [StructLayout(LayoutKind.Sequential)]
@@ -21,7 +22,7 @@ internal struct VBETypeLibObj
     }
 
     /// <summary>
-    /// An enumerable class for iterating over the double linked list of ITypeLibs provided by the VBE 
+    /// An enumerable class for iterating over the double linked list of <see cref="ITypeLib"/>s provided by the VBE 
     /// </summary>
     internal sealed class VBETypeLibsIterator : IEnumerable<ITypeLibWrapper>, IEnumerator<ITypeLibWrapper>
     {
diff --git a/Rubberduck.VBEEditor/ComManagement/TypeLibs/Utility/SimpleCustomTypeLibrary.cs b/Rubberduck.VBEEditor/ComManagement/TypeLibs/Utility/SimpleCustomTypeLibrary.cs
@@ -2,14 +2,14 @@
 using System.Collections.Generic;
 using System.Globalization;
 using System.Runtime.InteropServices;
-using Rubberduck.VBEditor.ComManagement.TypeLibs.Abstract;
 using Rubberduck.VBEditor.ComManagement.TypeLibs.Unmanaged;
 using ComTypes = System.Runtime.InteropServices.ComTypes;
 
 namespace Rubberduck.VBEditor.ComManagement.TypeLibs.Utility
 {
     /// <summary>
-    /// A custom implementation of ITypeLib.  A dumb container of ITypeInfos.
+    /// A custom implementation of <see cref="ComTypes.ITypeLib"/>.
+    /// A dumb container of ITypeInfos.
     /// </summary>
     /// <remarks>
     /// The TypeInfos it holds are disposed of elsewhere.

Original file line number	Diff line number	Diff line change
`@@ -6,7 +6,8 @@`
`6`	`6`	`namespace Rubberduck.VBEditor.ComManagement.TypeLibs`
`7`	`7`	`{`
`8`	`8`	`/// <summary>`
`9`		`- /// A class that represents a function definition within a <see cref="ComTypes.ITypeInfo"/>. Essentially a wrapper for <see cref="ComTypes.FUNCDESC"/>.`
	`9`	`+ /// A class that represents a function definition described in <see cref="ComTypes.FUNCDESC"/>`
	`10`	`+ /// within a <see cref="ComTypes.ITypeInfo"/>.`
`10`	`11`	`/// </summary>`
`11`	`12`	`internal class TypeInfoFunction : ITypeInfoFunction`
`12`	`13`	`{`
Original file line number	Diff line number	Diff line change
`@@ -3,7 +3,7 @@`
`3`	`3`	`namespace Rubberduck.VBEditor.ComManagement.TypeLibs.Unmanaged`
`4`	`4`	`{`
`5`	`5`	`/// <summary>`
`6`		`- /// AddressableVariables aid creating and handling unmanaged data`
	`6`	`+ /// AddressableVariables aids in creating and handling unmanaged data`
`7`	`7`	`/// </summary>`
`8`	`8`	`/// <remarks>`
`9`	`9`	`/// AddressableVariables are created in unmanaged memory space, designed to aid creating addressable`
Original file line number	Diff line number	Diff line change
`@@ -128,7 +128,7 @@ internal static class ComHelper`
`128`	`128`	`public static bool DoesComObjPtrSupportInterface<T>(IntPtr comObjPtr)`
`129`	`129`	`{`
`130`	`130`	`var iid = typeof(T).GUID;`
`131`		`- int hr = RdMarshal.QueryInterface(comObjPtr, ref iid, out var outInterfacePtr);`
	`131`	`+ var hr = RdMarshal.QueryInterface(comObjPtr, ref iid, out var outInterfacePtr);`
`132`	`132`	`if (!ComHelper.HRESULT_FAILED(hr))`
`133`	`133`	`{`
`134`	`134`	`RdMarshal.Release(outInterfacePtr);`
Original file line number	Diff line number	Diff line change
`@@ -5,7 +5,7 @@`
`5`	`5`	`namespace Rubberduck.VBEditor.ComManagement.TypeLibs.Unmanaged`
`6`	`6`	`{`
`7`	`7`	`/// <summary>`
`8`		`- /// This class marshals ComTypes.ITypeInfo members to ITypeInfoInternal`
	`8`	`+ /// This class marshals <see cref="ComTypes.ITypeInfo"/> members to <see cref="ITypeInfoInternal"/>`
`9`	`9`	`/// </summary>`
`10`	`10`	`/// <remarks>`
`11`	`11`	`/// ITypeInfoInternal must be inherited BEFORE ComTypes.ITypeInfo as they both have the same IID`