Rubberduck: Allow @Description and @ModuleDescription in Excel Workbook and Worksheet modules

[ChrisBrackett]

Justification
Most of the VBA I code is in locked down Excel Workbook projects designed to take user input and external data and output summary information, reports or files for import into another program. In this use, individual Excel Worksheets play unique rolls in the process that need to be documented.

Description
I would love to extend Rubberduck's indispensable @ModuleDescription and @Description annotations to include Workbook and Worksheet modules and event the overall Project (Excel or other MS Office file).

Worksheets themselves are often intended for specific purposes, such as data entry, syncing data from external sources or summary reporting and a back-end description and I think that documenting that along with the purpose of VBA in those Worksheets is just as helpful here as it is in code and class modules.

In addition to regular procedures, Worksheets can also have Event procedures that need to be documented (I currently document them using my pre-Rubberduck method as a comment inside the procedure). Here's an example description for a Workbook_AfterSave() event:

' DESCRIPTION: Recalculates the -FileNameError- named Range which compares the period in the file name to the period on the Worksheet.

Worksheets can have Form Controls that point to procedures on the sheet and ActiveX Controls with procedures directly linked to the procedure name such as Private Sub MyActiveXButton_Click().

@ProjectDescription annotations would also be useful – entered in the Workbook module and displayed when the project is selected in the Code Explorer.

[retailcoder]

The reason document modules can't have attribute annotations is because we can't export them, add the attributes, and re-import them back in.

Best we could do is let these modules have the annotation without treating it as illegal, and have the context/selection toolbar and Code Explorer use the annotations to display descriptions.

[ChrisBrackett]

Wouldn't your suggested workaround work for description annotations in general? Do you prefer to store annotations as module attributes?

[retailcoder]

Module/member VB_Description attributes show up in the Object Browser, so yeah whenever possible it's best to have them there.

[ChrisBrackett]

Makes sense. Still, it would be nice to have all my descriptions in RD regardless of the mechanism.

[retailcoder]

Looking at the RubberduckCommandBar code...

https://github.com/rubberduck-vba/Rubberduck/blob/0db534ed9b63f4ff84b36baf3ae9ad89b1749486/Rubberduck.Core/UI/Command/MenuItems/CommandBars/RubberduckCommandBar.cs#L58-L72

...as well as the CodeExplorerItemViewModel code:

https://github.com/rubberduck-vba/Rubberduck/blob/3b366dc25032041f42ee634f3a15dc935c2ec28f/Rubberduck.Core/Navigation/CodeExplorer/CodeExplorerItemViewModelBase.cs#L81

Looks like all we need to do is amend how the Declaration.DescriptionString is put together:

https://github.com/rubberduck-vba/Rubberduck/blob/189aa1ce552c0805e3591971c4389c494d02a92d/Rubberduck.Parsing/Symbols/Declaration.cs#L284-L309

And that looks fairly easy: simply query the _annotations collection (.OfType<DescriptionAnnotation>() for member-level, .OfType<ModuleDescriptionAnnotation>() for module-level) when there's no description attribute, instead of returning an empty string.

[retailcoder]

A side-effect of this, is that annotated descriptions will start showing up in the Code Explorer and the context/selection toolbar even when there's no corresponding VB_Description attribute - for all module types, not just document modules.

[retailcoder]

oh, I forgot a thing: the IllegalAnnotationInspection needs a little tweak here, to explicitly allow (i.e. exclude from this LINQ query) ModuleDescriptionAnnotation and DescriptionAnnotation (other annotations are still illegal in document modules):

https://github.com/rubberduck-vba/Rubberduck/blob/0db534ed9b63f4ff84b36baf3ae9ad89b1749486/Rubberduck.CodeAnalysis/Inspections/Concrete/IllegalAnnotationInspection.cs#L79-L84

[ChrisBrackett]

A side-effect of this, is that annotated descriptions will start showing up in the Code Explorer and the context/selection toolbar even when there's no corresponding VB_Description attribute - for all module types, not just document modules.

To me that sounds more like a feature than a bug. Is there any reason this behavior would be undesirable?

[retailcoder]

Not all side-effects are undesirable! :smiley:

[retailcoder]