应该用什么语法编写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＃）。

• 根据难度（或缺少）给出一个给定示例的语言，以使用该语言中特定类型的参数。