c++ - COM SDK 参考文档应该用什么语法编写？

Question

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

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

Answer 1

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

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

Answer 2

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

这里有一些想法：

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

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

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