Question

我想知道我是否可以手动将注释添加到我正在项目中使用的COM类或枚举。

我们的大多数程序员都可以毫无困难地使用，但由于我们在这里有一些经验不足的程序员，我想知道是否可以改进文档，为我们公司使用的COM对象，接口和枚举添加一些注释。 / p>

类似的东西：


///<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
}

如果无法使用上述方法，那么可以直接在COM dll中添加注释吗？

顺便说一句，我正在使用c＃开发VS 2008。我正在尝试通过向COM对象添加一些注释来改进我们的程序员体验，以便Visual Studio在其文档界面中显示。

Answer 1

COM类型库做通过[helpstring]属性支持注释。许多COM感知开发环境在其编辑器中显示这些注释。但是，.NET不支持此功能，从已编译的代码生成类型库，删除所有注释。并且.NET中没有任何属性可以让Regasm.exe或Tlbexp.exe将其发送到.tlb。

如果你想追求这个，那么你将不得不写一个.idl文件。您可以使用OleView.exe，File + View Typelib命令从现有的.tlb中获取一个。然后，您可以编辑文件以插入[helpstring]属性，midl.exe可以将其转换回类型库。

关于它的残酷部分是，当C＃代码的公共接口发生变化时，你必须重做。没有工具就没有快乐。并且有自动化它以确保此类型库不会与C＃代码失去一步。这会产生可怕的运行时异常，无法诊断。像AccessViolationException一样。或者更糟糕的是，没有异常，只是当堆栈失衡时错误的值。我不知道现有的工具可以做到这一点。

Answer 2

在Visual Studio中，当您在DLL中定义的类上按F12（转到定义）时，Visual Studio会显示该类的C＃表示形式，以及它找到的有关该类的任何文档。通常（总是？）这样的文档与DLL一起存储在XML文件中。例如，名为Foo.dll的DLL将具有包含文档的Foo.xml文件。下面是一个显示XML外观的示例：

<?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>

XML文件必须放在主Interop程序集旁边，如果COM库是MyCom.DLL，它通常具有Interop.MyComLib.DLL等文件名。如果COM DLL没有特制的主Interop程序集，则Visual Studio将自动生成Interop程序集，在这种情况下，obj \ Debug文件夹中将有一个副本（用于调试版本），另一个副本位于obj \ Release文件夹（用于发布版本）。如果您创建这样的XML文件，并将其放在Interop DLL（而不是原始COM DLL！）旁边，那么VS应该能够找到它。

bin \ *文件夹中还有额外的副本，但Visual Studio不会在bin \ *中查找文档。

为了帮助您创建文档，您可以编写一个以Interop DLL命名的虚拟项目，使用公共，无操作代码：

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() {}
    }
}

在项目设置的“构建”选项卡中，启用“XML文档文件”复选框。然后构建项目，复制Interop DLL旁边的XML文件（并使用XML扩展名赋予它相同的名称），然后查看Visual Studio是否识别XML文件（您可能必须重新启动Visual Studio）。

P.S。 “helpstring”属性对我不起作用。我没有看到它在任何地方的Visual Studio中显示。有没有办法让它发挥作用？

Answer 3

你这样做的方式是行不通的。使用三斜杠表示注释会导致VS期望XML格式的文档。有关详细信息，请阅读this article。如果你做得对，你的程序员将通过IntelliSense查看文档。

Answer 4

没有任何答案确实回答了问题。答案很简单。在C＃中，可以使用[helpstring("...")]属性来记录COM对象（System.ComponentModel.DescriptionAttribute）。从.Net Framework 1.1版开始，'描述'属性可用。

例如C＃类定义：

  /// <summary>
  /// 4. 'Obj_Anforderung' - (Obj_request) <-- this works for documenting in XML for VS docs or documentation generation tools
  /// </summary>
#if COMLIB
  [ComVisible(true)]
  [Guid("E58D82B8-2104-4378-92AB-E63F2FAF1EE8")]
  [Description("4. 'Obj_Anforderung' - (Obj_request)")] // <-- this works for COM interops
#endif 
  [TypeConverter(typeof(ExpandableObjectConverter))]
  public class Obj_Anforderung : GdtObj
  {
  }

当使用COM Interop true和Com Visible编译C＃项目时，我们可以使用OLE-COM查看器查看其定义（任何VS都具有此工具-在visual studio子组下查看“程序”菜单）

[
  uuid(E58D82B8-2104-4378-92AB-E63F2FAF1EE8),
  version(1.0),
  helpstring("4. 'Obj_Anforderung' - (Obj_request)"),
  noncreatable,
  custom(0F21F359-AB84-41E8-9A78-36D110E6D2F9, "open.medical.gdt.definitions.Obj_Anforderung")
]
coclass Obj_Anforderung {
    [default] interface _Obj_Anforderung;
    interface _Object;
};

您将看到[helpstring]存在，并且可以使用任何支持COM [helpstring]的标准IDE进行查看。例如，旧的VB6会将其视为

Class Obj_Anforderung
    Member of open_medical_gdt
    4. 'Obj_Anforderung' - (Obj_request)

是的，这是.Net COM Interops支持（简化版）背后的基本思想。如果您有支持COM互操作的旧的，庞大而强大的应用程序，并且不想将其移植到另一种语言。您可以在.Net C＃中编写一段代码，而在旧应用程序中，只需将C＃引用为COM Interop对象库即可，因为它是该编程环境的一部分，因此可以正常使用它。

是否可以在C＃代码中向COM对象添加注释？

4 个答案: