updated parameter docs

retailcoder · retailcoder · commit 7524a7b19437 · 2020-04-26T19:43:21.000-04:00
diff --git a/Rubberduck.Parsing/Annotations/Concrete/DefaultMemberAnnotation.cs b/Rubberduck.Parsing/Annotations/Concrete/DefaultMemberAnnotation.cs
@@ -9,9 +9,6 @@ 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.
     /// </summary>
-    /// <parameter>
-    /// This annotation takes no argument.
-    /// </parameter>
     /// <example>
     /// <module name="Class1" type="Class Module">
     /// <![CDATA[
diff --git a/Rubberduck.Parsing/Annotations/Concrete/DescriptionAnnotation.cs b/Rubberduck.Parsing/Annotations/Concrete/DescriptionAnnotation.cs
@@ -7,9 +7,12 @@ 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>
-    /// 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 name="DocString" type="String">
+    /// 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>
+    /// This documentation string appears in the VBE's own Object Browser, as well as in various Rubberduck UI elements.
+    /// </remarks>
     /// <example>
     /// <module name="Class1" type="Class Module">
     /// <![CDATA[
diff --git a/Rubberduck.Parsing/Annotations/Concrete/EnumeratorMemberAnnotation.cs b/Rubberduck.Parsing/Annotations/Concrete/EnumeratorMemberAnnotation.cs
@@ -8,9 +8,6 @@ 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.
     /// </summary>
-    /// <parameter>
-    /// This annotation takes no argument.
-    /// </parameter>
     /// <example>
     /// <module name="Class1" type="Class Module">
     /// <![CDATA[
diff --git a/Rubberduck.Parsing/Annotations/Concrete/ExcelHotKeyAnnotation.cs b/Rubberduck.Parsing/Annotations/Concrete/ExcelHotKeyAnnotation.cs
@@ -10,8 +10,8 @@ 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 name="Key" type="String*1">
+    /// 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>
     /// <module name="Module1" type="Standard Module">
diff --git a/Rubberduck.Parsing/Annotations/Concrete/ExposedModuleAnnotation.cs b/Rubberduck.Parsing/Annotations/Concrete/ExposedModuleAnnotation.cs
@@ -7,9 +7,6 @@ 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.
     /// </summary>
-    /// <parameter>
-    /// This annotation takes no argument.
-    /// </parameter>
     /// <example>
     /// <module name="Class1" type="Class Module">
     /// <![CDATA[
diff --git a/Rubberduck.Parsing/Annotations/Concrete/FolderAnnotation.cs b/Rubberduck.Parsing/Annotations/Concrete/FolderAnnotation.cs
@@ -3,8 +3,8 @@
     /// <summary>
     /// @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 name="Path" type="String">
+    /// 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>
     /// <module name="Class1" type="Class Module">
diff --git a/Rubberduck.Parsing/Annotations/Concrete/IgnoreAnnotation.cs b/Rubberduck.Parsing/Annotations/Concrete/IgnoreAnnotation.cs
@@ -3,8 +3,8 @@
     /// <summary>
     /// @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 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>
     /// <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
@@ -3,7 +3,7 @@
     /// <summary>
     /// @IgnoreModule annotation, used for ignoring inspection results module-wide.
     /// </summary>
-    /// <parameter>
+    /// <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>
     /// <remarks>
diff --git a/Rubberduck.Parsing/Annotations/Concrete/IgnoreTestAnnotation.cs b/Rubberduck.Parsing/Annotations/Concrete/IgnoreTestAnnotation.cs
@@ -3,9 +3,6 @@
     /// <summary>
     /// @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>
diff --git a/Rubberduck.Parsing/Annotations/Concrete/InterfaceAnnotation.cs b/Rubberduck.Parsing/Annotations/Concrete/InterfaceAnnotation.cs
@@ -3,9 +3,6 @@
     /// <summary>
     /// @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>
diff --git a/Rubberduck.Parsing/Annotations/Concrete/MemberAttributeAnnotation.cs b/Rubberduck.Parsing/Annotations/Concrete/MemberAttributeAnnotation.cs
@@ -7,8 +7,11 @@ namespace Rubberduck.Parsing.Annotations
     /// <summary>
     /// @MemberAttribute annotation, allows specifying arbitrary VB_Attribute for members. Use the quick-fixes to "Rubberduck Opportunities" code inspections to synchronize annotations and attributes.
     /// </summary>
-    /// <parameter>
-    /// This annotation takes two comma-separated arguments: first the literal name of the member VB_Attribute, then the value of that attribute.
+    /// <parameter name="VB_Attribute" type="Identifier">
+    /// The literal identifier name of the member VB_Attribute.
+    /// </parameter>
+    /// <parameter name="Values" type="ParamArray">
+    /// The comma-separated attribute values, as applicable.
     /// </parameter>
     /// <remarks>
     /// The @MemberAttribute annotation cannot be used at module level. This separate annotation disambiguates any potential scoping issues that present themselves when the same name is used for both scopes.
diff --git a/Rubberduck.Parsing/Annotations/Concrete/ModuleAttributeAnnotation.cs b/Rubberduck.Parsing/Annotations/Concrete/ModuleAttributeAnnotation.cs
@@ -7,8 +7,11 @@ namespace Rubberduck.Parsing.Annotations
     /// <summary>
     /// @ModuleAttribute annotation, allows specifying arbitrary VB_Attribute for modules. Use the quick-fixes to "Rubberduck Opportunities" code inspections to synchronize annotations and attributes.
     /// </summary>
-    /// <parameter>
-    /// This annotation takes the literal name of the member VB_Attribute, then the comma-separated values of that attribute.
+    /// <parameter name="VB_Attribute" type="Identifier">
+    /// The literal identifier name of the member VB_Attribute.
+    /// </parameter>
+    /// <parameter name="Values" type="ParamArray">
+    /// The comma-separated attribute values, as applicable.
     /// </parameter>
     /// <example>
     /// <module name="Class1" type="Class Module">
diff --git a/Rubberduck.Parsing/Annotations/Concrete/ModuleCleanupAnnotation.cs b/Rubberduck.Parsing/Annotations/Concrete/ModuleCleanupAnnotation.cs
@@ -3,9 +3,6 @@
     /// <summary>
     /// @ModuleCleanup annotation, marks a procedure that the unit testing engine executes after all tests of a module have completed.
     /// </summary>
-    /// <parameter>
-    /// This annotation takes no argument.
-    /// </parameter>
     /// <example>
     /// <module name="TestModule1" type="Standard Module">
     /// <![CDATA[
diff --git a/Rubberduck.Parsing/Annotations/Concrete/ModuleDescriptionAnnotation.cs b/Rubberduck.Parsing/Annotations/Concrete/ModuleDescriptionAnnotation.cs
@@ -7,11 +7,12 @@ 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.
     /// </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 module attribute.
+    /// <parameter name="DocString" type="String">
+    /// 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 module level. This separate annotation disambiguates any potential scoping issues that present themselves when the same name is used for both scopes.
+    /// This documentation string appears in the VBE's own Object Browser, as well as in various Rubberduck UI elements.
     /// </remarks>
     /// <example>
     /// <module name="Class1" type="Class Module">
diff --git a/Rubberduck.Parsing/Annotations/Concrete/ModuleInitializeAnnotation.cs b/Rubberduck.Parsing/Annotations/Concrete/ModuleInitializeAnnotation.cs
@@ -3,9 +3,6 @@
     /// <summary>
     /// @ModuleInitialize annotation, marks a procedure that the unit testing engine executes before running the first test of a module.
     /// </summary>
-    /// <parameter>
-    /// This annotation takes no argument.
-    /// </parameter>
     /// <example>
     /// <module name="TestModule1" type="Standard Module">
     /// <![CDATA[
diff --git a/Rubberduck.Parsing/Annotations/Concrete/NoIndentAnnotation.cs b/Rubberduck.Parsing/Annotations/Concrete/NoIndentAnnotation.cs
@@ -3,9 +3,6 @@
     /// <summary>
     /// @NoIndent annotation, used by the "indent project" feature to ignore/skip particular modules when bulk-indenting.
     /// </summary>
-    /// <parameter>
-    /// This annotation takes no argument.
-    /// </parameter>
     /// <example>
     /// <module name="Class1" type="Class Module">
     /// <![CDATA[
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>
-    /// This annotation takes no argument.
+    /// <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>
     /// <example>
     /// <module name="Class1" type="Class Module">
diff --git a/Rubberduck.Parsing/Annotations/Concrete/PredeclaredIdAnnotation.cs b/Rubberduck.Parsing/Annotations/Concrete/PredeclaredIdAnnotation.cs
@@ -7,9 +7,6 @@ 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.
     /// </summary>
-    /// <parameter>
-    /// This annotation takes no argument.
-    /// </parameter>
     /// <remarks>
     /// Consider keeping the default/predeclared instance stateless.
     /// </remarks>
diff --git a/Rubberduck.Parsing/Annotations/Concrete/TestCleanupAnnotation.cs b/Rubberduck.Parsing/Annotations/Concrete/TestCleanupAnnotation.cs
@@ -3,9 +3,6 @@
     /// <summary>
     /// @TestCleanup annotation, marks a procedure that the unit testing engine executes once after running each of the tests in a module.
     /// </summary>
-    /// <parameter>
-    /// This annotation takes no argument.
-    /// </parameter>
     /// <example>
     /// <module name="TestModule1" type="Standard Module">
     /// <![CDATA[
diff --git a/Rubberduck.Parsing/Annotations/Concrete/TestInitializeAnnotation.cs b/Rubberduck.Parsing/Annotations/Concrete/TestInitializeAnnotation.cs
@@ -3,9 +3,6 @@
     /// <summary>
     /// @TestInitialize annotation, marks a procedure that the unit testing engine executes once before running each of the tests in a module.
     /// </summary>
-    /// <parameter>
-    /// This annotation takes no argument.
-    /// </parameter>
     /// <example>
     /// <module name="TestModule1" type="Standard Module">
     /// <![CDATA[
diff --git a/Rubberduck.Parsing/Annotations/Concrete/TestMethodAnnotation.cs b/Rubberduck.Parsing/Annotations/Concrete/TestMethodAnnotation.cs
@@ -7,8 +7,8 @@ namespace Rubberduck.Parsing.Annotations
     /// <summary>
     /// @TestMethod annotation, identifies procedures that contain unit tests.
     /// </summary>
-    /// <parameter>
-    /// This annotation takes an optional string argument identifying the test category.
+    /// <parameter name="TestCategory" type="String">
+    /// If arguments are supplied, the current implementation makes the first provided argument be the test category.
     /// </parameter>
     /// <example>
     /// <module name="TestModule1" type="Standard Module">
diff --git a/Rubberduck.Parsing/Annotations/Concrete/TestModuleAnnotation.cs b/Rubberduck.Parsing/Annotations/Concrete/TestModuleAnnotation.cs
@@ -3,9 +3,6 @@
     /// <summary>
     /// @TestModule annotation, marks a module for unit test discovery.
     /// </summary>
-    /// <parameter>
-    /// This annotation takes no argument.
-    /// </parameter>
     /// <remarks>
     /// The test engine only scans modules with this annotation when discovering unit tests.
     /// </remarks>
diff --git a/Rubberduck.Parsing/Annotations/Concrete/VariableDescriptionAnnotation.cs b/Rubberduck.Parsing/Annotations/Concrete/VariableDescriptionAnnotation.cs
@@ -7,9 +7,6 @@ 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.
     /// </summary>
-    /// <parameter>
-    /// This annotation takes no argument.
-    /// </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>
