Is it possible to add comments to COM objects inside C# code?

Question

I was wondering if I can manually add comments to a COM class or enum that I'm using in my project.

Most of our programmers can use then without any trouble, but since we got some inexperienced programers in here, I was wondering if I could improve documentation adding some comments to the COM objects, interfaces and enums we use in our company.

Something like:

///<summary>This is a enum that doesn't do anything</summary>
enum ComApi.FooBar
{
  ///<summary>Does Foo</summary>
  Foo,
  ///<summary>Does Bar</summary>
  Bar,
  ///<summary>Does Foo and Bar, and divid by zero!</summary>
  Baz
}

If the above way is not possible, then is it possible to add the comments directly inside the COM dll?

By the way, I'm developing on VS 2008, with c#. I'm trying to improve our programmers experience by adding some comments to the COM objects, so that Visual Studio shows then in it's documentation interface.

Answer 1

In Visual Studio, when you press F12 (Go To Definition) on a class that is defined in a DLL, Visual Studio shows a C# representation of the class, along with any documentation it finds about that class. Normally (always?) such documentation is stored in an XML file alongside the DLL. For example, a DLL called Foo.dll would have a Foo.xml file that contains documentation. Here is an example showing what the XML looks like:

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>Interop.MyComLib</name>
    </assembly>
    <members>
        <member name="T:MyComLib.IMyInterface">
            <summary>
            An interface for transforming actionable items into itemed actions.
            </summary>
        </member>
        <member name="M:MyComLib.IMyInterface.Dance(System.Boolean)">
            <summary>
            Causes any pending phat moves to be flushed to corporeal
            form in a visually pleasing manner.
            </summary>
            <param name="b">Must be true, or there will be a FalseException.</param>
            <returns>A <see cref="T:System.Boolean"/> containing the opposite of the 'b' argument.</returns>
        </member>
    </members>
</doc>

The XML file must be placed alongside the Primary Interop Assembly, which typically has a filename such as Interop.MyComLib.DLL if the COM library is MyCom.DLL. If the COM DLL doesn't have a specially-made Primary Interop Assembly then Visual Studio will generate an Interop assembly automatically, in which case there will be one copy in your obj\Debug folder (for the debug build) and another copy in the obj\Release folder (for the release build). If you make an XML file like this, and put it next to the Interop DLL (not the original COM DLL!) then VS should be able to find it.

There are also extra copies in the bin\* folders, but Visual Studio does not look for documentation in bin\*.

To help you create documentation, you could write a dummy project named after the Interop DLL, with public, do-nothing code:

namespace ComApiLib
{
    /// <summary>This is a enum that doesn't do anything</summary>
    public enum ComApi.FooBar
    {
      ///<summary>Does Foo</summary>
      Foo,
      ///<summary>Does Bar</summary>
      Bar,
    }
    /// <summary>This is a class</summary>
    public class Klass
    {
        ///<summary>Does Foo</summary>
        public void Foo() {}
        ///<summary>Does Bar</summary>
        public void Bar() {}
    }
}

In the project settings, in the Build tab, enable the "XML documentation file" checkbox. Then build your project, copy the XML file beside the Interop DLL (and give it the same name with XML extension), then see if Visual Studio recognizes the XML file (you might have to restart Visual Studio).

P.S. The "helpstring" attribute doesn't work for me. I don't see it displayed in Visual Studio anywhere. Is there a way to make it work?