应该写什么语法的COM SDK参考文档？

Question

我有一个用C++编写的COM SDK，我想为我的产品创建文档。据我所知，大多数人可能不会使用C++来与这个COM组件集成，但很多人会这样做。

哪种方法最适合描述API，而不会丢失C++开发人员需要知道的细节。

Answer 1

您可以使用helpstring属性直接在IDL中编写文档 - 您的代码的大多数用户将能够使用例如OLE视图或其对象浏览器直接读取该文档。我们公司编写了一个内部工具来提取帮助文档，并将其转化为HTML中的内部参考文档。

此外，您可以使用像doxygen这样的工具来记录界面 - 它将输出HTML，PDF，LaTeX等格式的文档。

Answer 2

IDL肯定是一个参考的好主意。但我想你会想提供代码示例和片段。

这里有几个想法：

• 它暴露出什么样的COM接口的？ IDispatch，自定义，双重？您可能通过猜测您的SDK受众是谁做出了决定，因此他们使用的是什么语言。

• 您是否应该只使用一种语言？也许你可以用C++提供一些例子，一些用VB6，一些用.NET（VB或C＃）。

• 根据难度（或缺乏）使用该语言中特定类型的参数来选择给定示例的语言。