reworded xmldoc content for attribute annotations, changed a parameter types e.g. "String" to "Text" as per review comments

retailcoder · retailcoder · commit 41261864a647 · 2020-07-23T16:29:13.000-04:00
diff --git a/Rubberduck.CodeAnalysis/Inspections/Concrete/ThunderCode/OnErrorGoToMinusOneInspection.cs b/Rubberduck.CodeAnalysis/Inspections/Concrete/ThunderCode/OnErrorGoToMinusOneInspection.cs
@@ -13,7 +13,7 @@ namespace Rubberduck.CodeAnalysis.Inspections.Concrete.ThunderCode
     /// <why>
     /// This inpection is flagging code we dubbed "ThunderCode", 
     /// code our friend Andrew Jackson would have written to confuse Rubberduck's parser and/or resolver. 
-    /// 'On Error GoTo -1' is poorly documented and uselessly complicates error handling.
+    /// 'On Error GoTo -1' is poorly documented and uselessly complicates error handling. Consider using 'On Error GoTo 0' instead.
     /// </why>
     internal sealed class OnErrorGoToMinusOneInspection : ParseTreeInspectionBase<VBAParser.OnErrorStmtContext>
     {
diff --git a/Rubberduck.Parsing/Annotations/Concrete/DefaultMemberAnnotation.cs b/Rubberduck.Parsing/Annotations/Concrete/DefaultMemberAnnotation.cs
@@ -7,7 +7,7 @@
 namespace Rubberduck.Parsing.Annotations
 {
     /// <summary>
-    /// @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.
+    /// @DefaultMember annotation, indicates that the member should have a VB_UserMemId attribute value (0) making it the default member of that class. Use the quick-fixes to "Rubberduck Opportunities" code inspections to synchronize annotations and attributes.
     /// </summary>
     /// <example>
     /// <module name="Class1" type="Class Module">
diff --git a/Rubberduck.Parsing/Annotations/Concrete/DescriptionAnnotation.cs b/Rubberduck.Parsing/Annotations/Concrete/DescriptionAnnotation.cs
@@ -7,7 +7,7 @@ namespace Rubberduck.Parsing.Annotations
     /// <summary>
     /// @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 name="DocString" type="String">
+    /// <parameter name="DocString" type="Text">
     /// This string literal parameter does not support expressions and/or multiline inputs. The string literal is used as-is as the value of the hidden member attribute.
     /// </parameter>
     /// <remarks>
diff --git a/Rubberduck.Parsing/Annotations/Concrete/EnumeratorMemberAnnotation.cs b/Rubberduck.Parsing/Annotations/Concrete/EnumeratorMemberAnnotation.cs
@@ -6,7 +6,7 @@
 namespace Rubberduck.Parsing.Annotations
 {
     /// <summary>
-    /// @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.
+    /// @Enumerator annotation, indicates that the member should have a VB_UserMemId attribute value (-4) making it 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>
     /// <example>
     /// <module name="Class1" type="Class Module">
diff --git a/Rubberduck.Parsing/Annotations/Concrete/ExcelHotKeyAnnotation.cs b/Rubberduck.Parsing/Annotations/Concrete/ExcelHotKeyAnnotation.cs
@@ -8,9 +8,9 @@
 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.
+    /// @ExcelHotkey annotation, indicates the presence of a VB_ProcData.VB_Invoke_Func metadata attribute value that maps a hotkey to a standard module procedure ("macro"). Use the quick-fixes to "Rubberduck Opportunities" code inspections to synchronize annotations and attributes.
     /// </summary>
-    /// <parameter name="Key" type="String*1">
+    /// <parameter name="Key" type="Text">
     /// A single-letter string argument maps 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>
diff --git a/Rubberduck.Parsing/Annotations/Concrete/ExposedModuleAnnotation.cs b/Rubberduck.Parsing/Annotations/Concrete/ExposedModuleAnnotation.cs
@@ -5,7 +5,7 @@
 namespace Rubberduck.Parsing.Annotations
 {
     /// <summary>
-    /// @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.
+    /// @Exposed annotation, indicates the presence of a VB_Exposed module attribute value (True) to make a class visible to a referencing project (classes are otherwise private by default). Use the quick-fixes to "Rubberduck Opportunities" code inspections to synchronize annotations and attributes.
     /// </summary>
     /// <example>
     /// <module name="Class1" type="Class Module">
diff --git a/Rubberduck.Parsing/Annotations/Concrete/FolderAnnotation.cs b/Rubberduck.Parsing/Annotations/Concrete/FolderAnnotation.cs
@@ -1,9 +1,9 @@
 ﻿namespace Rubberduck.Parsing.Annotations
 {
     /// <summary>
-    /// @Folder annotation, determines where in a custom folder structure a given module appears in the Code Explorer toolwindow.
+    /// @Folder annotation, used by Rubberduck to represent and organize modules under a custom folder structure.
     /// </summary>
-    /// <parameter name="Path" type="String">
+    /// <parameter name="Path" type="Text">
     /// This string literal argument uses the dot "." character to indicate parent/child folders. Consider using folder names that are valid in the file system; PascalCase names are ideal.
     /// </parameter>
     /// <example>
@@ -16,6 +16,18 @@
     /// End Sub
     /// ]]>
     /// </module>
+    /// <module name="Module1" type="Standard Module">
+    /// <![CDATA[
+    /// '@Folder("Parent.Child")
+    /// Option Explicit
+    ///
+    /// Public Sub Macro1()
+    ///     With New Class1 '@Folder does not affect namespace or referencing code in any way.
+    ///         .DoSomething
+    ///     End With
+    /// End Sub
+    /// ]]>
+    /// </module>
     /// </example>
     public sealed class FolderAnnotation : AnnotationBase
     {
diff --git a/Rubberduck.Parsing/Annotations/Concrete/IgnoreAnnotation.cs b/Rubberduck.Parsing/Annotations/Concrete/IgnoreAnnotation.cs
@@ -1,10 +1,10 @@
 ﻿namespace Rubberduck.Parsing.Annotations
 {
     /// <summary>
-    /// @Ignore annotation, used for ignoring inspection results at member and local level.
+    /// @Ignore annotation, used by Rubberduck to filter inspection results at member and local level.
     /// </summary>
-    /// <parameter name="Inspections" type="ParamArray (Identifier)">
-    /// This annotation optionally takes a comma-separated list of inspection names as argument. If no specific inspection is provided, then all inspections should ignore the annotated target.
+    /// <parameter name="Inspections" type="InspectionNames">
+    /// This annotation takes a comma-separated list of inspection names as arguments (at least one is required).
     /// </parameter>
     /// <remarks>
     /// Use the @IgnoreModule annotation to annotate at module level.
diff --git a/Rubberduck.Parsing/Annotations/Concrete/IgnoreModuleAnnotation.cs b/Rubberduck.Parsing/Annotations/Concrete/IgnoreModuleAnnotation.cs
@@ -1,13 +1,13 @@
 ﻿namespace Rubberduck.Parsing.Annotations
 {
     /// <summary>
-    /// @IgnoreModule annotation, used for ignoring inspection results module-wide.
+    /// @IgnoreModule annotation, used by Rubberduck to filter inspection results module-wide.
     /// </summary>
-    /// <parameter name="Inspections" type="ParamArray (Identifier)">
-    /// 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 name="Inspections" type="InspectionNames">
+    /// This annotation optionally takes a comma-separated list of inspection names as argument. If no specific inspection name is provided, then all inspections should ignore the annotated module.
     /// </parameter>
     /// <remarks>
-    /// Use this annotation judiciously: while it silences false positives, it also silences legitimate inspection results.
+    /// Use this annotation judiciously: while it silences false positives, it also silences legitimate inspection results; useful for muting results in legacy code while still inspecting new code.
     /// </remarks>
     /// <example>
     /// <module name="Class1" type="Class Module">
diff --git a/Rubberduck.Parsing/Annotations/Concrete/IgnoreTestAnnotation.cs b/Rubberduck.Parsing/Annotations/Concrete/IgnoreTestAnnotation.cs
@@ -1,10 +1,13 @@
 ﻿namespace Rubberduck.Parsing.Annotations
 {
     /// <summary>
-    /// @IgnoreTest annotation, used for ignoring a particular unit test in a test module.
+    /// @IgnoreTest annotation, used by Rubberduck for skipping a particular test when running the tests of a test module.
     /// </summary>
+    /// <parameter name="Reason" type="Text">
+    /// An optional argument/comment describing the reason for ignoring the test.
+    /// </parameter>
     /// <remarks>
-    /// Test Explorer will skip tests decorated with this annotation.
+    /// Test Explorer will skip tests decorated with this annotation. Use the ignore/un-ignore commands to automatically add or remove this annotation to a particular test without browsing to its source.
     /// </remarks>
     /// <example>
     /// <module name="Tests" type="Standard Module">
@@ -14,7 +17,7 @@
     ///
     /// '...
     /// 
-    /// '@IgnoreTest
+    /// '@IgnoreTest("Foo is currently breaking this test, see issue #42")
     /// '@TestMethod("Category")
     /// Private Sub GivenFoo_DoesBar()
     ///     '...
diff --git a/Rubberduck.Parsing/Annotations/Concrete/ModuleCleanupAnnotation.cs b/Rubberduck.Parsing/Annotations/Concrete/ModuleCleanupAnnotation.cs
@@ -1,7 +1,7 @@
 ﻿namespace Rubberduck.Parsing.Annotations
 {
     /// <summary>
-    /// @ModuleCleanup annotation, marks a procedure that the unit testing engine executes after all tests of a module have completed.
+    /// @ModuleCleanup annotation, marks a procedure that Rubberduck executes after all tests of a module have completed.
     /// </summary>
     /// <example>
     /// <module name="TestModule1" type="Standard Module">
diff --git a/Rubberduck.Parsing/Annotations/Concrete/ModuleDescriptionAnnotation.cs b/Rubberduck.Parsing/Annotations/Concrete/ModuleDescriptionAnnotation.cs
@@ -5,9 +5,9 @@
 namespace Rubberduck.Parsing.Annotations
 {
     /// <summary>
-    /// @ModuleDescription annotation, uses the VB_Description module attribute to provide a docstring for a module. Use the quick-fixes to "Rubberduck Opportunities" code inspections to synchronize annotations and attributes.
+    /// @ModuleDescription annotation, indicates the presence of a VB_Description module attribute value providing a docstring for the module. Use the quick-fixes to "Rubberduck Opportunities" code inspections to synchronize annotations and attributes.
     /// </summary>
-    /// <parameter name="DocString" type="String">
+    /// <parameter name="DocString" type="Text">
     /// This string literal parameter does not support expressions and/or multiline inputs. The string literal is used as-is as the value of the hidden member attribute.
     /// </parameter>
     /// <remarks>
diff --git a/Rubberduck.Parsing/Annotations/Concrete/ModuleInitializeAnnotation.cs b/Rubberduck.Parsing/Annotations/Concrete/ModuleInitializeAnnotation.cs
@@ -1,7 +1,7 @@
 ﻿namespace Rubberduck.Parsing.Annotations
 {
     /// <summary>
-    /// @ModuleInitialize annotation, marks a procedure that the unit testing engine executes before running the first test of a module.
+    /// @ModuleInitialize annotation, marks a procedure that Rubberduck executes before running the first test of a module.
     /// </summary>
     /// <example>
     /// <module name="TestModule1" type="Standard Module">
diff --git a/Rubberduck.Parsing/Annotations/Concrete/NotRecognizedAnnotation.cs b/Rubberduck.Parsing/Annotations/Concrete/NotRecognizedAnnotation.cs
@@ -1,8 +1,8 @@
 ﻿namespace Rubberduck.Parsing.Annotations
 {
-    /// <summary>
-    /// Used for all annotations not recognized by RD.
-    /// Since this is not actually an annotation, it has no valid target
+    /// <summary hidden="true">
+    /// The annotation type Rubberduck uses for comments that correctly parse as annotations, but weren't recognized as such.
+    /// Since this is not actually an annotation, it has no valid target.
     /// </summary>
     public sealed class NotRecognizedAnnotation : AnnotationBase
     {
diff --git a/Rubberduck.Parsing/Annotations/Concrete/ObsoleteAnnotation.cs b/Rubberduck.Parsing/Annotations/Concrete/ObsoleteAnnotation.cs
@@ -7,8 +7,8 @@ namespace Rubberduck.Parsing.Annotations
     /// <summary>
     /// @Obsolete annotation, marks a procedure as "obsolete". Rubberduck inspections can then warn about code that references them.
     /// </summary>
-    /// <parameter name="Message" type="String" required="False">
-    /// If provided, the first argument becomes additional metadata that Rubberduck can use in inspection results, for example.
+    /// <parameter name="Message" type="Text" required="False">
+    /// If provided, the first argument becomes additional metadata that Rubberduck can use in inspection results, and remains a valid and useful in-place comment.
     /// </parameter>
     /// <example>
     /// <module name="Class1" type="Class Module">
diff --git a/Rubberduck.Parsing/Annotations/Concrete/PredeclaredIdAnnotation.cs b/Rubberduck.Parsing/Annotations/Concrete/PredeclaredIdAnnotation.cs
@@ -5,7 +5,7 @@
 namespace Rubberduck.Parsing.Annotations
 {
     /// <summary>
-    /// @PredeclaredId annotation, uses the VB_Predeclared module attribute to define a compile-time default instance for the class. Use the quick-fixes to "Rubberduck Opportunities" code inspections to synchronize annotations and attributes.
+    /// @PredeclaredId annotation, indicates the presence of VB_Predeclared module attribute value (True) that defines a default instance for the class, named after that class. Use the quick-fixes to "Rubberduck Opportunities" code inspections to synchronize annotations and attributes.
     /// </summary>
     /// <remarks>
     /// Consider keeping the default/predeclared instance stateless.
diff --git a/Rubberduck.Parsing/Annotations/Concrete/TestCleanupAnnotation.cs b/Rubberduck.Parsing/Annotations/Concrete/TestCleanupAnnotation.cs
@@ -1,7 +1,7 @@
 ﻿namespace Rubberduck.Parsing.Annotations
 {
     /// <summary>
-    /// @TestCleanup annotation, marks a procedure that the unit testing engine executes once after running each of the tests in a module.
+    /// @TestCleanup annotation, marks a procedure that Rubberduck executes once after running each of the tests in a module.
     /// </summary>
     /// <example>
     /// <module name="TestModule1" type="Standard Module">
diff --git a/Rubberduck.Parsing/Annotations/Concrete/TestInitializeAnnotation.cs b/Rubberduck.Parsing/Annotations/Concrete/TestInitializeAnnotation.cs
@@ -1,7 +1,7 @@
 ﻿namespace Rubberduck.Parsing.Annotations
 {
     /// <summary>
-    /// @TestInitialize annotation, marks a procedure that the unit testing engine executes once before running each of the tests in a module.
+    /// @TestInitialize annotation, marks a procedure that Rubberduck executes once before running each of the tests in a module.
     /// </summary>
     /// <example>
     /// <module name="TestModule1" type="Standard Module">
diff --git a/Rubberduck.Parsing/Annotations/Concrete/TestMethodAnnotation.cs b/Rubberduck.Parsing/Annotations/Concrete/TestMethodAnnotation.cs
@@ -5,9 +5,9 @@
 namespace Rubberduck.Parsing.Annotations
 {
     /// <summary>
-    /// @TestMethod annotation, identifies procedures that contain unit tests.
+    /// @TestMethod annotation, identifies a procedure that constitutes a unit test.
     /// </summary>
-    /// <parameter name="TestCategory" type="String">
+    /// <parameter name="TestCategory" type="Text">
     /// If arguments are supplied, the current implementation makes the first provided argument be the test category.
     /// </parameter>
     /// <example>
diff --git a/Rubberduck.Parsing/Annotations/Concrete/TestModuleAnnotation.cs b/Rubberduck.Parsing/Annotations/Concrete/TestModuleAnnotation.cs
@@ -4,7 +4,7 @@
     /// @TestModule annotation, marks a module for unit test discovery.
     /// </summary>
     /// <remarks>
-    /// The test engine only scans modules with this annotation when discovering unit tests.
+    /// Rubberduck only scans modules with this annotation when discovering unit tests in a project.
     /// </remarks>
     /// <example>
     /// <module name="TestModule1" type="Standard Module">
diff --git a/Rubberduck.Parsing/Annotations/Concrete/VariableDescriptionAnnotation.cs b/Rubberduck.Parsing/Annotations/Concrete/VariableDescriptionAnnotation.cs
@@ -5,8 +5,11 @@
 namespace Rubberduck.Parsing.Annotations
 {
     /// <summary>
-    /// @VariableDescription annotation, uses the VB_VarDescription attribute to provide a docstring for a module-level variable or constant. Use the quick-fixes to "Rubberduck Opportunities" code inspections to synchronize annotations and attributes.
+    /// @VariableDescription annotation, indicates the presence of a VB_VarDescription attribute value providing a docstring for a module-level variable or constant. Use the quick-fixes to "Rubberduck Opportunities" code inspections to synchronize annotations and attributes.
     /// </summary>
+    /// <parameter name="DocString" type="Text">
+    /// This string literal parameter does not support expressions and/or multiline inputs. The string literal is used as-is as the value of the hidden member attribute.
+    /// </parameter>
     /// <remarks>
     /// The @Description annotation cannot be used at the module variable level. This separate annotation disambiguates any potential scoping issues that present themselves when the same name is used for both scopes.
     /// </remarks>

Original file line number	Diff line number	Diff line change
`@@ -13,7 +13,7 @@ namespace Rubberduck.CodeAnalysis.Inspections.Concrete.ThunderCode`
`13`	`13`	`/// <why>`
`14`	`14`	`/// This inpection is flagging code we dubbed "ThunderCode",`
`15`	`15`	`/// code our friend Andrew Jackson would have written to confuse Rubberduck's parser and/or resolver.`
`16`		`- /// 'On Error GoTo -1' is poorly documented and uselessly complicates error handling.`
	`16`	`+ /// 'On Error GoTo -1' is poorly documented and uselessly complicates error handling. Consider using 'On Error GoTo 0' instead.`
`17`	`17`	`/// </why>`
`18`	`18`	`internal sealed class OnErrorGoToMinusOneInspection : ParseTreeInspectionBase<VBAParser.OnErrorStmtContext>`
`19`	`19`	`{`
Original file line number	Diff line number	Diff line change
`@@ -7,7 +7,7 @@`
`7`	`7`	`namespace Rubberduck.Parsing.Annotations`
`8`	`8`	`{`
`9`	`9`	`/// <summary>`
`10`		`- /// @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.`
	`10`	`+ /// @DefaultMember annotation, indicates that the member should have a VB_UserMemId attribute value (0) making it the default member of that class. Use the quick-fixes to "Rubberduck Opportunities" code inspections to synchronize annotations and attributes.`
`11`	`11`	`/// </summary>`
`12`	`12`	`/// <example>`
`13`	`13`	`/// <module name="Class1" type="Class Module">`
Original file line number	Diff line number	Diff line change
`@@ -6,7 +6,7 @@`
`6`	`6`	`namespace Rubberduck.Parsing.Annotations`
`7`	`7`	`{`
`8`	`8`	`/// <summary>`
`9`		`- /// @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.`
	`9`	`+ /// @Enumerator annotation, indicates that the member should have a VB_UserMemId attribute value (-4) making it 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.`
`10`	`10`	`/// </summary>`
`11`	`11`	`/// <example>`
`12`	`12`	`/// <module name="Class1" type="Class Module">`
Original file line number	Diff line number	Diff line change
`@@ -5,7 +5,7 @@`
`5`	`5`	`namespace Rubberduck.Parsing.Annotations`
`6`	`6`	`{`
`7`	`7`	`/// <summary>`
`8`		`- /// @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.`
	`8`	`+ /// @Exposed annotation, indicates the presence of a VB_Exposed module attribute value (True) to make a class visible to a referencing project (classes are otherwise private by default). Use the quick-fixes to "Rubberduck Opportunities" code inspections to synchronize annotations and attributes.`
`9`	`9`	`/// </summary>`
`10`	`10`	`/// <example>`
`11`	`11`	`/// <module name="Class1" type="Class Module">`