Initially introduced solely to mark test modules and methods for unit test discovery, Rubberduck annotation comments have significantly evolved since their inception, and today they're fully integrated into the parsing strategy.
Rubberduck still uses annotations for unit test discovery, but also for ignoring specific inspections or inspection results either locally or module-wide; some annotations map to hidden module and member attributes and can be used to surface such metadata and easily manipulate attribute values such as `VB_Description`, `VB_UserMemId`, and `VB_PredeclaredId` - _without needing to manually export, edit, and re-import_ any code file.
The following annotations are all legal and equivalent:
'@AnnotationName "Argument1", Argument2
#### [Annotation Targets](#annotation-targets)
Each annotation has a _target_ that can be a _declaration_ or an _identifier reference_. Annotations that target declarations can apply to _modules_ or their _members_, but not both because the placement of an annotation could be ambiguous:
'@Description "Is this a description of the module or the procedure?"
Public Sub DoSomething()
In the above example, the `@Description` annotation is targeting the `DoSomething` procedure. In order to provide a description for the module itself, we need another annotation - enter `@ModuleDescription`:
'@ModuleDescription "This is a description of the module"
'@Description "This is a description of the procedure"
Public Sub DoSomething()
Rubberduck inspections will warn about annotations that are misplaced or not aimed at an appropriate target, for example if `@Description` appears to be used at module-level.
#### [Annotation Inspections](#annotation-inspections)
Several code inspections work with annotations and attributes, notably annotations that Rubberduck uses to synchronize hidden attributes and their values. See:
- [Annotation in incompatible component type](/inspections/Details/AnnotationInIncompatibleComponentType)
- [Attribute value out of sync](/inspections/Details/AttributeValueOutOfSync)
- [Duplicated annotation](/inspections/Details/DuplicatedAnnotation)
- [Invalid annotation](/inspections/Details/InvalidAnnotation) (formerly `IllegalAnnotation`)
- [Missing annotation argument](/inspections/Details/MissingAnnotationArgument)
- [Missing attribute](/inspections/Details/MissingAttribute)
- [Missing member annotation](/inspections/Details/MissingMemberAnnotation)
- [Missing module annotation](/inspections/Details/MissingModuleAnnotation)
- [Superfluous annotation argument](/inspections/Details/SuperfluousAnnotationArgument)
- [Unrecognized annotation](/inspections/Details/UnrecognizedAnnotation)
#### [Annotation Quick-Fixes](#annotation-quick-fixes)
Most inspection results can be locally muted using an `@Ignore` annotation, or module-wide with an `@IgnoreModule` annotation. These annotations are automatically inserted by Rubberduck when a quick-fix such as _ignore once_ or _ignore in module_ is selected. Inspections flagging a missing attribute have quick-fixes that make Rubberduck automatically export, edit, and re-import a module with the attribute set as per the corresponding annotation comment. See:
- [Add attribute annotation](/FeatureDetails?name=AddAttributeAnnotationQuickFix)
- [Add missing attribute](/FeatureDetails?name=AddMissingAttributeQuickFix)
- [Adjust attribute annotation](/FeatureDetails?name=AdjustAttributeAnnotationQuickFix)
- [Adjust attribute values](/FeatueDetails?name=AdjustAttributeValuesQuickFix)
- [Ignore in module](/FeatureDetails?name=IgnoreInModuleQuickFix)
- [Ignore once](/FeatureDetails?name=IgnoreOnceQuickFix)
- [Remove annotation](/FeatureDetails?name=RemoveAnnotationQuickFix)
- [Remove attribute](/FeatureDetails?name=RemoveAttributeQuickFix)
- [Remove duplicated annotation](/FeatureDetails?name=RemoveDuplicatedAnnotation)
API call did not return a success response :(