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)
Make that "three single comment-markers"
In C# it's ///
which as default spits out:
/// <summary>
///
/// </summary>
/// <returns></returns>
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).
It has support for C#, VB.NET and C/C++. It is per default mapped to Ctrl+Shift+D.
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.
///
is the shortcut for getting the Method Description comment block. But make sure you have written the function name and signature before adding it. First write the Function name and signature.
Then above the function name just type ///
and you will get it automatically
Visual Assist has a nice solution too, and is highly customizable.
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.)
Edit: The way to customize the 'document method' text is under VassistX->Visual Assist Options->Suggestions, select 'Edit VA Snippets', Language: C++, Type: Refactoring, then go to 'Document Method' and customize. The above example is generated by:
To Insert The Snippet: with cursor in method name/signature, alt+shift+q > "document method"
Normally, Visual Studio creates it automatically if you add three single comment-markers above the thing you like to comment (method, class).
In C# this would be ///.
If Visual Studio doesn't do this, you can enable it in
Options->Text Editor->C#->Advanced
and check
Generate XML documentation comments for ///
In visual basic, if you create your function/sub first, then on the line above it, you type ' three times, it will auto-generate the relevant xml for documentation. This also shows up when you mouseover in intellisense, and when you are making use of the function.
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.
I'm working on an open-source project called Todoc which analyzes words to produce proper documentation output automatically when saving a file. It respects existing comments and is really fast and fluid.
