Using GhostDoc in a macro to comment an entire solution

At work we've started leveraging Visual Studio Team System to essentially automate the checking of Standards and Best Practices (S&BPs). We decided that anything that could be automatically enforced could be deemed part of the S&BPs because it was cost effective. Anything else could be deemed guidance but would not be required. One of the aspects that we desired was being able to effectively use Sandcastle to generate technical documentation. I personally feel that the most valuable documentation from XML comments comes form the comments on Acceptance Tests since they define the expectations of the system. To make those XML comments required we created a shared MSBuild file that treated some of the XML compiler warnings as errors.

Playing Catch-Up
This unfortunately left us with a lot of catch-up work. We needed to fill in and correct thousands of missing comments. While it would have been the most valuable to add thoughtful defined explanations in those places it also would have been the most costly - and it wasn't in our project budget to take on that cost. As a result I adapted a Visual Studio macro with some code-DOM traversing material borrowed from TeamReview in order to leverage GhostDoc to automatically fill in missing comments and fix some comment structure for an entire Visual Studio solution. This allowed us to take on the endeavor of changing our S&BPs, being able to enforce them for the better, and allowed us to move forward without immediately paying for Technical Debt due to the change in S&BPs.


Again, GhostDoc comments are meant to get us over the hurdle of not being able to enforce a coding standard. I know as well as you that auto-generated stuff isn't very valuable, but without it we wouldn't be able to approach this endeavor.

Before you run the macro
Be sure your code compiles and that you have the entire solution checked out from source control. Otherwise you'll get lots and lots of prompts, potentially two for every file.

Below is the code. The macro is named after the Winston Wolf character in the movie Pulp Fiction.

The Code

Option Explicit Off
Imports System
Imports EnvDTE
Imports EnvDTE80
Imports EnvDTE90
Imports System.Diagnostics

Public Module TheWolf

Public Sub CleanUpSolution()
IterateFiles()
End Sub


Private Sub IterateFiles()
Dim project As EnvDTE.Project
Dim projects As EnvDTE.Projects
Dim window As Window
Dim target As Object
DTE.ExecuteCommand("View.
SolutionExplorer")
window = DTE.Windows.Item(Constants.vsWindowKindCommandWindow)
projects = DTE.Solution.Projects
If projects.Count = 0 Then
  Exit Sub
End If


For Each project In projects
  If (Not project.ProjectItems Is Nothing) Then
      CleanUpProject(project.ProjectItems())
  End If
Next
'RebuildSolution()
End Sub

Private Sub CleanUpProject(ByVal items)
Dim file As ProjectItem
For Each file In items
  If file.Name.EndsWith(".cs") OrElse file.Name.EndsWith(".vb") Then
      ActivateFile(file)
      RemoveAndSortUsings()
      FormatDocument()
      DocumentCode(file)
  End If

  'Handle folders within a project
  If Not file.ProjectItems() Is Nothing Then
      If file.ProjectItems.Count > 0 Then
          CleanUpProject(file.ProjectItems())
      End If
  End If
  SaveAll()
  CloseAll()
Next
End Sub

Private Sub RebuildSolution()
DTE.ExecuteCommand("Build.RebuildSolution")
End Sub

Private Sub SaveAll()
Try
  DTE.ExecuteCommand("File.SaveAll")
Catch ex As Exception
End Try
End Sub

Private Sub CloseAll()
Try
  DTE.ExecuteCommand("File.CloseAllButThis")
  DTE.ExecuteCommand("File.Close")
Catch ex As Exception
End Try
End Sub

Private Sub ActivateFile(ByVal file As ProjectItem)
file.Open()
If (Not file.Document Is Nothing) Then
  file.Document.Activate()
End If
Try
  DTE.ExecuteCommand("View.ViewCode")
Catch ex As Exception
  'do nothing - it's probably already viewable
End Try
End Sub

Private Sub RemoveAndSortUsings()
Try
  DTE.ExecuteCommand("Edit.RemoveAndSort")
Catch ex As Exception
  'does not work on VB code
End Try
End Sub

Private Sub FormatDocument()
DTE.ExecuteCommand("Edit.FormatDocument")
End Sub

Private Sub DocumentCode(ByVal file As ProjectItem)
Dim element As EnvDTE.CodeElement
Dim document As EnvDTE.TextDocument
document = CType(file.Document.Object(""), EnvDTE.TextDocument)
If (document Is Nothing) Then
  Return
End If
DocumentElements(document, file.FileCodeModel.CodeElements)
End Sub

Private Sub DocumentElement(ByVal document As EnvDTE.TextDocument, ByVal element As EnvDTE.CodeElement)
Dim startPoint As EnvDTE.EditPoint
document.Selection.GotoLine(element.StartPoint.Line, True)
startPoint = document.CreateEditPoint(document.Selection.ActivePoint)
document.Selection.MoveToPoint(startPoint, True)
DTE.ExecuteCommand("Weigelt.GhostDoc.AddIn.DocumentThis")
End Sub

Private Sub DocumentElements(ByVal document As EnvDTE.TextDocument, ByVal elements As EnvDTE.CodeElements)
Try
  For Each element In elements

      Select Case element.Kind
          Case vsCMElement.vsCMElementFunction
              Dim func As EnvDTE.CodeFunction
              func = CType(element, EnvDTE.CodeFunction)
              If (func.Access <> vsCMAccess.vsCMAccessPrivate And func.Access <> vsCMAccess.vsCMAccessProject) Then
                  DocumentElement(document, element)
              End If
              DocumentElements(document, func.Children)
          Case vsCMElement.vsCMElementProperty
              Dim prop As EnvDTE.CodeProperty
              prop = CType(element, EnvDTE.CodeProperty)
              If (prop.Access <> vsCMAccess.vsCMAccessPrivate And prop.Access <> vsCMAccess.vsCMAccessProject) Then
                  DocumentElement(document, element)
              End If
              DocumentElements(document, prop.Children)
          Case vsCMElement.vsCMElementEvent
              Dim evt As EnvDTE80.CodeEvent
              evt = CType(element, EnvDTE80.CodeEvent)
              If (evt.Access <> vsCMAccess.vsCMAccessPrivate And evt.Access <> vsCMAccess.vsCMAccessProject) Then
                  DocumentElement(document, element)
              End If
              DocumentElements(document, evt.Children)
          Case vsCMElement.vsCMElementClass
              Dim cls As EnvDTE.CodeClass
              cls = CType(element, EnvDTE.CodeClass)
              If (cls.Access <> vsCMAccess.vsCMAccessPrivate And cls.Access <> vsCMAccess.vsCMAccessProject) Then
                  DocumentElement(document, element)
              End If
              DocumentElements(document, cls.Children)
          Case vsCMElement.vsCMElementStruct
              Dim strct As EnvDTE.CodeStruct
              strct = CType(element, EnvDTE.CodeStruct)
              If (strct.Access <> vsCMAccess.vsCMAccessPrivate And strct.Access <> vsCMAccess.vsCMAccessProject) Then
                  DocumentElement(document, element)
              End If
              DocumentElements(document, strct.Children)
          Case vsCMElement.vsCMElementDelegate
              Dim dlg As EnvDTE.CodeDelegate
              dlg = CType(element, EnvDTE.CodeDelegate)
              If (dlg.Access <> vsCMAccess.vsCMAccessPrivate And dlg.Access <> vsCMAccess.vsCMAccessProject) Then
                  DocumentElement(document, element)
              End If
              DocumentElements(document, dlg.Children)
          Case vsCMElement.vsCMElementEnum
              Dim enm As EnvDTE.CodeEnum
              enm = CType(element, EnvDTE.CodeEnum)
              If (enm.Access <> vsCMAccess.vsCMAccessPrivate And enm.Access <> vsCMAccess.vsCMAccessProject) Then
                  DocumentElement(document, element)
              End If
              DocumentElements(document, enm.Children)
          Case (vsCMElement.vsCMElementVariable)
              Dim var As EnvDTE.CodeVariable

              var = CType(element, EnvDTE.CodeVariable)
              If (var.Access <> vsCMAccess.vsCMAccessPrivate And var.Access <> vsCMAccess.vsCMAccessProject) Then
                  DocumentElement(document, element)
              End If
          Case vsCMElement.vsCMElementNamespace
              Dim nmspc As EnvDTE.CodeNamespace
              nmspc = CType(element, EnvDTE.CodeNamespace)
              DocumentElements(document, nmspc.Children)
                Case vsCMElement.vsCMElementInterface
              Dim inter As EnvDTE.CodeInterface
              inter = CType(element, EnvDTE.CodeInterface)
              If (inter.Access <> vsCMAccess.vsCMAccessPrivate And inter.Access <> vsCMAccess.vsCMAccessProject) Then
                  DocumentElement(document, element)
              End If              
              DocumentElements(document, inter.Children)
            End Select

  Next
Catch ex As Exception

End Try

End Sub

End Module