You can automate Visual Studio by getting or creating an instance of EnvDTE.DTE. For example, you can create a new VS 2015 instance with the following code:
System.Type dteType = Type.GetTypeFromProgID("VisualStudio.DTE.14.0", true);
EnvDTE.DTE dte = (EnvDTE.DTE)System.Activator.CreateInstance(dteType);Each Visual Studio version has its own progID. For example, VS 2015 has "VisualStudio.DTE.14.0" and VS 2013 has "VisualStudio.DTE.12.0".
As you know, almost every operation in Visual Studio is implemented as a named command. Visual Studio provides its built-in commands and extensions can add their own. For example, our VSdocman provides commands for compiling a documentation. You can invoke the commands from Command Window. Just start typing and it will offer you a list of available commands. You can optionally supply arguments for the command. When you press Enter, the command will be executed. For example, if you type Help.About, the About window will be displayed. Similarly, if you type VSdocman.CompileProject "SampleClassLibrary", it will compile a documentation for the SampleClassLibrary project.
While you can run any batch command in your build events, there's no way to execute a Visual Studio command during the build (at least, I'm not aware of any). So I created a reusable MSBuild task that you can use for executing any named VS command, when the build is performed inside Visual Studio.
When you write XML doc comments in your .NET code for your internal purposes, you usually don't care about their formal perfectness. All you need is to be clear and precise.
The situation is however different, when it comes to commenting an API that will be publicly available to the end-users. The documentation must be clear, formally correct and consistent.
I'm not going to talk about a grammar, English is not my strong point. But I will show you the most common mistakes and some simple rules that can make your documentation even better. The list is by no way complete. I collected it from my experiences with my own or my clients' APIs and from what I have observed in MSDN. The points are in random order. All improvements can be done manually without any tool, but where appropriate, I will show how they can be simplified with our VSdocman, especially with its WYSIWYG comment editor.
1. Don't hardcode true, false, null, Nothing, static and other language specific keywords.
2. Don't put “obsolete” info directly in XML comments, use ObsoleteAttribute.
3. Use a definition list for describing predefined values
4. Document each enumeration item, don't place its description to the parent enumeration comments
5. Don't duplicate enum description in methods that use the enumeration
6. Use <see> if you're referring to another member
7. Use <paramref> if you're referring to another parameter in the same method
8. Member summary is a description, not a command
It was some time ago when a user of our VSdocman reported about 20 second delay when he invoked some of its functions. It wasn't that easy to fix it because we couldn't reproduce the issue on our side. Finally we have found the reason, created a workaround in our code and forgot it.
Recently, I've encountered a similar problem and it took some time to recall that we have already faced it. So I'm putting the info here for my own reference and for anyone else.
Direct link to the multiline search extension
It's been 8 years since I wrote a Multiline Search and Replace macro for Visual Studio. At that time, I only needed some multi-line replacements and I had no idea how popular the macro could be. A lot of comments and visits proved that this is really something MS should implement directly in VS. Now we have VS 2013 and multiline find and replace still isn't there. What's worse, support for macros was removed from VS 2012 and higher, but that's another topic. So neither my macro helps now.
So I converted the macro to Visual Studio package (extension) and now you can use it in Visual Studio 2005-2013. You can download it here.
