views:

2738

answers:

4

When I type the trigger the auto comment feature in Visual Studio (by typing "'''" or "///"), most of the XML commenting details show up that I like. However, I typically add the history tag to the documentation so I can track and changes that are made to the method over time.

Is there any way I can customize the auto commenting feature so that it will add the history tag, and potentially some generic Name - Date - Change placeholder text?

+7  A: 

I'd suggest using GhostDoc. It generates very smart comments using /// based on your method names and parameters. Also, it is fully customizable.

DavGarcia
Excellent resource! Unfortunately we're a VB shop here and GhostDoc is listed as "experimental" for VB.NET code. I am keeping this bookmarked for my own C# projects at home though. Thanks!
Dillie-O
Doh >_< I was going to ask if you were using VB or C# too. Ah well...
DavGarcia
Just by means of an update, GhostDoc 2.5 fully supports commenting in VB.NET. I simply went to the GhostDoc Options and added my history tag (with a variable to put in the current date) and I was all set.
Dillie-O
+3  A: 

I think that you could use a tool as dgarcia said but try to chose one that makes the version control insetad, Personally I'm not a huge fan of keep the "history" or track of the project using comments in the code.

If you like that way you could create your own customized version of the snippet, this is easier if you use a tool like Snippy

Copy this file to your

My Documents\Visual Studio 2005\Code Snippets[Language]\My Code Snippets\

Just be carefull to change the file if you gonna use it in VB.NET

Hope this help

Rulas
A: 

The auto commenting text feature is actually a pre-defined macro that you can edit.

You just need to go the the macro editor (warning : I think it's not installed by the visual studio default setup) : go to the Tools menu -> Macros -> Macro editor.

The function is called "InsertDocComments" and is located in the "Utilities" file of the "Samples" project.

Olivier PAYEN
I found the section you mentioned and added some code (similar to the comment tag code in the function). I've saved, done a rebuild, even exited and restarted Visual Studio, but the tags aren't showing up. Any ideas?
Dillie-O
A: 

Just as followup to the comment to Olivier. Here is a copy of the macro now, look for the '' Do History section to see where I inserted code.

    ''// InsertDocComments goes through the current document using the VS Code Model
    ''// to add documentation style comments to each function.
    ''
    Sub InsertDocComments()
        Dim projectItem As ProjectItem
        Dim fileCodeModel As FileCodeModel
        Dim codeElement As CodeElement
        Dim codeElementType As CodeType
        Dim editPoint As EditPoint
        Dim commentStart As String

        projectItem = DTE.ActiveDocument.ProjectItem
        fileCodeModel = projectItem.FileCodeModel
        codeElement = fileCodeModel.CodeElements.Item(1)

        ''// For the sample, don't bother recursively descending all code like
        ''// the OutlineCode sample does. Just get a first CodeType in the
        ''// file.
        If (TypeOf codeElement Is CodeNamespace) Then
            codeElement = codeElement.members.item(1)
        End If
        If (TypeOf codeElement Is CodeType) Then
            codeElementType = CType(codeElement, CodeType)
        Else
            Throw New Exception("Didn't find a type definition as first thing in file or find a namespace as the first thing with a type inside the namespace.")
        End If

        editPoint = codeElementType.GetStartPoint(vsCMPart.vsCMPartHeader).CreateEditPoint()

        ''// Make doc comment start.
        commentStart = LineOrientedCommentStart()
        If (commentStart.Length = 2) Then
            commentStart = commentStart & commentStart.Chars(1) & " "
        ElseIf (commentStart.Length = 1) Then
            commentStart = commentStart & commentStart.Chars(0) & commentStart.Chars(0) & " "
        End If

        ''// Make this atomically undo'able.  Use Try...Finally to ensure Undo
        ''// Context is close.
        Try
            DTE.UndoContext.Open("Insert Doc Comments")

            ''// Iterate over code elements emitting doc comments for functions.
            For Each codeElement In codeElementType.Members
                If (codeElement.Kind = vsCMElement.vsCMElementFunction) Then
                    ''// Get Params.
                    Dim parameters As CodeElements
                    Dim codeFunction As CodeFunction
                    Dim codeElement2 As CodeElement
                    Dim codeParameter As CodeParameter

                    codeFunction = codeElement
                    editPoint.MoveToPoint(codeFunction.GetStartPoint(vsCMPart.vsCMPartHeader))
                    ''//editPoint.LineUp()
                    parameters = codeFunction.Parameters

                    ''// Do comment.
                    editPoint.Insert(Microsoft.VisualBasic.Constants.vbCrLf)
                    editPoint.LineUp()
                    editPoint.Insert(Microsoft.VisualBasic.Constants.vbTab & commentStart & "<summary>")
                    editPoint.Insert(Microsoft.VisualBasic.Constants.vbCrLf)
                    editPoint.Insert(Microsoft.VisualBasic.Constants.vbTab & commentStart & "Summary of " & codeElement.Name & ".")
                    editPoint.Insert(Microsoft.VisualBasic.Constants.vbCrLf)
                    editPoint.Insert(Microsoft.VisualBasic.Constants.vbTab & commentStart & "</summary>")
                    editPoint.Insert(Microsoft.VisualBasic.Constants.vbCrLf)
                    editPoint.Insert(Microsoft.VisualBasic.Constants.vbTab & commentStart)

                    For Each codeElement2 In parameters
                        codeParameter = codeElement2
                        editPoint.Insert("<param name=" & codeParameter.Name & "></param>")
                        editPoint.Insert(Microsoft.VisualBasic.Constants.vbCrLf)
                        editPoint.Insert(Microsoft.VisualBasic.Constants.vbTab & commentStart)
                    Next ''//param

                    ''// Do history tag.
                    editPoint.Insert(Microsoft.VisualBasic.Constants.vbCrLf)
                    editPoint.LineUp()
                    editPoint.Insert(Microsoft.VisualBasic.Constants.vbTab & commentStart & "<history>")
                    editPoint.Insert(Microsoft.VisualBasic.Constants.vbCrLf)
                    editPoint.Insert(Microsoft.VisualBasic.Constants.vbTab & commentStart & "Name   MM/DD/YYYY   [Created]")
                    editPoint.Insert(Microsoft.VisualBasic.Constants.vbCrLf)
                    editPoint.Insert(Microsoft.VisualBasic.Constants.vbTab & commentStart & "</history>")
                    editPoint.Insert(Microsoft.VisualBasic.Constants.vbCrLf)
                    editPoint.Insert(Microsoft.VisualBasic.Constants.vbTab & commentStart)

                End If ''//we have a function
            Next ''//code elt member

        Finally
            DTE.UndoContext.Close()
        End Try
    End Sub

For some reason, after a save, rebuild, and a restart of Visual Studio, I'm not getting the history tag. Can anybody see something here I'm missing?

Dillie-O
I don't think this macro is what the Visual Studio IDE uses when you type ''' before a Sub. You can run your modified macro by right clicking on it in the Macro Explorer and selecting Run. This inserts comments before every routine, whether or not they are already commented.
Patrick McDonald
Hmm, sounds like something to try. Any idea on what the actual macro name is that runs?
Dillie-O