added xmldocs for annotations, fixes #5380

Author: retailcoder

Rubberduck.Parsing/Annotations/Concrete/DefaultMemberAnnotation.cs

@@ -7,8 +7,33 @@
 namespace Rubberduck.Parsing.Annotations
 {
     /// <summary>
-    /// Used for specifying a member's <c>VB_UserMemId</c> attribute value.
+    /// @DefaultMember annotation, uses the VB_UserMemId attribute to make a class member the default member of that class. Use the quick-fixes to "Rubberduck Opportunities" code inspections to synchronize annotations and attributes.
     /// </summary>
+    /// <parameter>
+    /// This annotation takes no argument.
+    /// </parameter>
+    /// <example>
+    /// <module name="Class1" type="Class Module">
+    /// <![CDATA[
+    /// Option Explicit
+    /// Private InternalState As VBA.Collection
+    ///
+    /// @DefaultMember
+    /// Public Property Get Item(ByVal Index As Variant) As Variant
+    ///     Item = InternalState(Index)
+    /// End Sub
+    /// 
+    /// 'if the default member is a property, only the Get accessor needs the attribute/annotation.
+    /// Public Property Let Item(ByVal Index As Variant, ByVal Value As Variant)
+    ///     InternalState(Index) = Value    
+    /// End Sub
+    /// 
+    /// Private Sub Class_Initialize()
+    ///     Set InternalState = New VBA.Collection
+    /// End Sub
+    /// ]]>
+    /// </module>
+    /// </example>
     public sealed class DefaultMemberAnnotation : FixedAttributeValueAnnotationBase
     {
         public DefaultMemberAnnotation()

Rubberduck.Parsing/Annotations/Concrete/DescriptionAnnotation.cs

@@ -5,8 +5,22 @@
 namespace Rubberduck.Parsing.Annotations
 {
     /// <summary>
-    /// Used for specifying a member's <c>VB_Description</c> attribute.
+    /// @Description annotation, uses the VB_Description member attribute to provide a docstring for a module member. Use the quick-fixes to "Rubberduck Opportunities" code inspections to synchronize annotations and attributes.
     /// </summary>
+    /// <parameter>
+    /// This annotation takes a single string literal parameter that does not support expressions and/or multiline inputs. The string literal is used as-is as the value of the hidden member attribute.
+    /// </parameter>
+    /// <example>
+    /// <module name="Class1" type="Class Module">
+    /// <![CDATA[
+    /// Option Explicit
+    ///
+    /// @Description("Does something")
+    /// Public Sub DoSomething()
+    /// End Sub
+    /// ]]>
+    /// </module>
+    /// </example>
     public sealed class DescriptionAnnotation : DescriptionAttributeAnnotationBase
     {
         public DescriptionAnnotation()

Rubberduck.Parsing/Annotations/Concrete/EnumeratorMemberAnnotation.cs

@@ -6,8 +6,28 @@
 namespace Rubberduck.Parsing.Annotations
 {
     /// <summary>
-    /// Used for specifying a member's <c>VB_UserMemId</c> attribute value.
+    /// @Enumerator annotation, uses the VB_UserMemId attribute to make a class member the enumerator-provider member of that class, enabling For Each iteration of custom collections. Use the quick-fixes to "Rubberduck Opportunities" code inspections to synchronize annotations and attributes.
     /// </summary>
+    /// <parameter>
+    /// This annotation takes no argument.
+    /// </parameter>
+    /// <example>
+    /// <module name="Class1" type="Class Module">
+    /// <![CDATA[
+    /// Option Explicit
+    /// Private InternalState As VBA.Collection
+    ///
+    /// @Enumerator
+    /// Public Property Get NewEnum() As IUnknown
+    ///     Set NewEnum = InternalState.[_NewEnum]
+    /// End Sub
+    /// 
+    /// Private Sub Class_Initialize()
+    ///     Set InternalState = New VBA.Collection
+    /// End Sub
+    /// ]]>
+    /// </module>
+    /// </example>
     public sealed class EnumeratorMemberAnnotation : FixedAttributeValueAnnotationBase
     {
         public EnumeratorMemberAnnotation()

Rubberduck.Parsing/Annotations/Concrete/ExcelHotKeyAnnotation.cs

@@ -7,6 +7,24 @@
 
 namespace Rubberduck.Parsing.Annotations
 {
+    /// <summary>
+    /// @ExcelHotkey annotation, uses a VB_ProcData.VB_Invoke_Func metadata attribute to map a hotkey to a standard module procedure. Use the quick-fixes to "Rubberduck Opportunities" code inspections to synchronize annotations and attributes.
+    /// </summary>
+    /// <parameter>
+    /// This annotation requires a single-letter string argument to map the hotkey. If the letter is in UPPER CASE, the hotkey is Ctrl+Shift+letter; if the letter is lower case, the hotkey is Ctrl+letter. Avoid remapping commonly used keyboard shortcuts!
+    /// </parameter>
+    /// <example>
+    /// <module name="Module1" type="Standard Module">
+    /// <![CDATA[
+    /// Option Explicit
+    ///
+    /// @ExcelHotkey("D")
+    /// Public Sub DoSomething()
+    ///     '...
+    /// End Sub
+    /// ]]>
+    /// </module>
+    /// </example>
     public sealed class ExcelHotKeyAnnotation : FlexibleAttributeValueAnnotationBase
     {
         public ExcelHotKeyAnnotation()

Rubberduck.Parsing/Annotations/Concrete/ExposedModuleAnnotation.cs

@@ -5,8 +5,22 @@
 namespace Rubberduck.Parsing.Annotations
 {
     /// <summary>
-    /// Used for specifying a module's <c>VB_Exposed</c> attribute.
+    /// @Exposed annotation, uses the VB_Exposed module attribute to make a class visible to a referencing project (classes are otherwise private). Use the quick-fixes to "Rubberduck Opportunities" code inspections to synchronize annotations and attributes.
     /// </summary>
+    /// <parameter>
+    /// This annotation takes no argument.
+    /// </parameter>
+    /// <example>
+    /// <module name="Class1" type="Class Module">
+    /// <![CDATA[
+    /// '@Exposed
+    /// Option Explicit
+    ///
+    /// Public Sub DoSomething()
+    /// End Sub
+    /// ]]>
+    /// </module>
+    /// </example>
     public sealed class ExposedModuleAnnotation : FixedAttributeValueAnnotationBase
     {
         public ExposedModuleAnnotation()

Rubberduck.Parsing/Annotations/Concrete/FolderAnnotation.cs

@@ -1,8 +1,22 @@
 namespace Rubberduck.Parsing.Annotations
 {
     /// <summary>
-    /// Used for specifying the Code Explorer folder a appears under.
+    /// @Folder annotation, determines where in a custom folder structure a given module appears in the Code Explorer toolwindow.
     /// </summary>
+    /// <parameter>
+    /// This annotation takes a single string literal argument that uses the dot "." character to indicate parent/child folders. Consider using folder names that are valid in the file system; PascalCase names is ideal.
+    /// </parameter>
+    /// <example>
+    /// <module name="Class1" type="Class Module">
+    /// <![CDATA[
+    /// '@Folder("Parent.Child.SubChild")
+    /// Option Explicit
+    ///
+    /// Public Sub DoSomething()
+    /// End Sub
+    /// ]]>
+    /// </module>
+    /// </example>
     public sealed class FolderAnnotation : AnnotationBase
     {
         public FolderAnnotation()

Rubberduck.Parsing/Annotations/Concrete/IgnoreAnnotation.cs

@@ -1,8 +1,35 @@
 namespace Rubberduck.Parsing.Annotations
 {
     /// <summary>
-    /// Used for ignoring specific inspection results from a specified set of inspections.
+    /// @Ignore annotation, used for ignoring inspection results at member and local level.
     /// </summary>
+    /// <parameter>
+    /// This annotation optionally takes a comma-separated list of inspection names as argument. If no specific inspection is provided, then all inspections would ignore the annotated target.
+    /// </parameter>
+    /// <remarks>
+    /// Use the @IgnoreModule annotation to annotate at module level.
+    /// </remarks>
+    /// <example>
+    /// <module name="Class1" type="Class Module">
+    /// <![CDATA[
+    /// Option Explicit
+    /// Private InternalState As VBA.Collection
+    ///
+    /// '@Ignore
+    /// Public Sub DoSomething(ByRef foo As Long)
+    ///     foo = 42
+    /// End Sub
+    /// 
+    /// '@Ignore ProcedureNotUsed
+    /// Public Sub DoSomethingElse()
+    ///     '@Ignore VariableNotAssigned
+    ///     Dim result As Variant
+    ///     DoSomething result
+    ///     Debug.Print result
+    /// End Sub
+    /// ]]>
+    /// </module>
+    /// </example>
     public sealed class IgnoreAnnotation : AnnotationBase
     {
         public IgnoreAnnotation()

Rubberduck.Parsing/Annotations/Concrete/IgnoreModuleAnnotation.cs

@@ -1,8 +1,37 @@
 namespace Rubberduck.Parsing.Annotations
 {
     /// <summary>
-    /// This annotation allows ignoring inspection results of defined inspections for a whole module
+    /// @IgnoreModule annotation, used for ignoring inspection results module-wide.
     /// </summary>
+    /// <parameter>
+    /// This annotation optionally takes a comma-separated list of inspection names as argument. If no specific inspection is provided, then all inspections would ignore the annotated module.
+    /// </parameter>
+    /// <remarks>
+    /// Use this annotation judiciously: while it silences false positives, it also silences legitimate inspection results.
+    /// </remarks>
+    /// <example>
+    /// <module name="Class1" type="Class Module">
+    /// <![CDATA[
+    /// '@IgnoreModule
+    /// Option Explicit
+    ///
+    /// Public Sub DoSomething()
+    /// End Sub
+    /// ]]>
+    /// </module>
+    /// </example>
+    /// <example>
+    /// <module name="Class1" type="Class Module">
+    /// <![CDATA[
+    /// '@IgnoreModule UndeclaredVariable, VariableNotUsed, VariableNotAssigned, UnassignedVariableUsage
+    ///
+    /// Public Sub DoSomething()
+    ///     foo = 42
+    ///     Debug.Print bar
+    /// End Sub
+    /// ]]>
+    /// </module>
+    /// </example>
     public sealed class IgnoreModuleAnnotation : AnnotationBase
     {
         public IgnoreModuleAnnotation()

Rubberduck.Parsing/Annotations/Concrete/IgnoreTestAnnotation.cs

@@ -1,8 +1,30 @@
 namespace Rubberduck.Parsing.Annotations
 {
     /// <summary>
-    /// Used to indicate the test engine that a unit test is to be ignored.
+    /// @IgnoreTest annotation, used for ignoring a particular unit test in a test module.
     /// </summary>
+    /// <parameter>
+    /// This annotation takes no argument.
+    /// </parameter>
+    /// <remarks>
+    /// Test Explorer will skip tests decorated with this annotation.
+    /// </remarks>
+    /// <example>
+    /// <module name="Tests" type="Standard Module">
+    /// <![CDATA[
+    /// '@TestModule
+    /// Option Explicit
+    ///
+    /// '...
+    /// 
+    /// '@IgnoreTest
+    /// '@TestMethod("Category")
+    /// Private Sub GivenFoo_DoesBar()
+    ///     '...
+    /// End Sub
+    /// ]]>
+    /// </module>
+    /// </example>
     public sealed class IgnoreTestAnnotation : AnnotationBase
     {
         public IgnoreTestAnnotation()

Rubberduck.Parsing/Annotations/Concrete/InterfaceAnnotation.cs

@@ -1,8 +1,25 @@
 namespace Rubberduck.Parsing.Annotations
 {
     /// <summary>
-    /// Used to mark a class module as an interface, so that Rubberduck treats it as such even if it's not implemented in any opened project.
+    /// @Interface annotation, marks a class as an abstract interface; Rubberduck can use this valuable metadata in its code analysis.
     /// </summary>
+    /// <parameter>
+    /// This annotation takes no argument.
+    /// </parameter>
+    /// <remarks>
+    /// Code Explorer uses an "interface" icon to represent class modules with this annotation.
+    /// </remarks>
+    /// <example>
+    /// <module name="Tests" type="Standard Module">
+    /// <![CDATA[
+    /// '@Interface
+    /// Option Explicit
+    ///
+    /// Public Sub DoSomething()
+    /// End Sub
+    /// ]]>
+    /// </module>
+    /// </example>
     public sealed class InterfaceAnnotation : AnnotationBase
     {
         public InterfaceAnnotation()