views:

5700

answers:

4

I was wondering if there is a way (hopefully keyboard shortcut) to create auto generate function headers in visual studio.

Example:

Private Function Foo(ByVal param1 As String, ByVal param2 As Integer)

And it would automagically become something like this...


'----------------------------------
'Pre:
'Post:
'Author:
'Date:
'Param1 (String):
'Param2 (Integer):
'Summary:
Private Function Foo(ByVal param1 As String, ByVal param2 As Integer)

A: 

You can use code snippets to insert any lines you want.

Also, if you type three single quotation marks (''') on the line above the function header, it will insert the XML header template that you can then fill out.

These XML comments can be interpreted by documentation software, and they are included in the build output as an assembly.xml file. If you keep that XML file with the DLL and reference that DLL in another project, those comments become available in intellisense.

NYSystemsAnalyst
That's VB.NET: in C# it's ///
peSHIr
+6  A: 

make that "three single comment-markers"

In C# it's ///

which as default spits out:

    /// <summary>
    /// 
    /// </summary>
    /// <returns></returns>

Here's some tips on editing VS templates.

Michael Paulukonis
Agreed, technically incorrect word choice on my part.
NYSystemsAnalyst
And in VB.NET it's triple single quotes (as mentioned in other answer)
peSHIr
That's pretty neat, didn't know about that
Brendan
The tips link is now broken
Eric
Updated tips link
Michael Paulukonis
+3  A: 

GhostDoc!

Right-click on the function, select "Document this" and

private bool FindTheFoo(int numberOfFoos)

becomes

/// <summary>
/// Finds the foo.
/// </summary>
/// <param name="numberOfFoos">The number of foos.</param>
/// <returns></returns>
private bool FindTheFoo(int numberOfFoos)

(yes, it is all autogenerated).

According to the webpage:

support for VB.Net is "experimental"

but it should be worth a try. I am sure it can be mapped to a key, too.

Remember: you should add information beyond the method signature to the documentation. Don't just stop with the autogenerated documentation. The value of a tool like this is that it automatically generates the documentation that can be extracted from the method signature, so any information you add should be new information.

That being said, I personally prefer when methods are totally selfdocumenting, but sometimes you will have coding-standards that mandate outside documentation, and then a tool like this will save you a lot of braindead typing.

Rasmus Faber
And this is exactly the kind of 'documentation' that I detest. It just adds bytes without telling me anything the method and parameter names don't tell me already. Do not do this, without editing the comment into some worth-while... :-(
peSHIr
Of course you should be editing it to add information. But as a template it is very nice.
Rasmus Faber
+2  A: 

Visual Assist have a nice solution too, and is highly costumizable.

After tweaking it to generate doxygen-style comments, these two clicks would produce -

/**
* Method:    FindTheFoo
* FullName:  FindTheFoo
* Access:    private 
* Qualifier:
* @param    int numberOfFoos
* @return   bool
*/
private bool FindTheFoo(int numberOfFoos)
{

}

(Under default settings, its a bit different.)

Ofek Shilon