c - 专业#include内容

Question

我需要创建一个 API，允许我客户的开发人员使用将作为库发布的专有 C 模块(想想 .lib 或 .so - - 不是来源)。

我想让 header 尽可能对开发人员友好(所以我不需要这样做)，遵循最佳实践并提供带有描述、示例、注意事项的评论，等。

从业务、技术和普通常识的角度来看，我还应该考虑什么？

谢谢!

Answer 1

一种选择是使用(例如)Doxygen 从 header 生成 API 文档。显然，您仍会随代码一起发布文档。

这有两个好处:

1) 您不必太担心某些内容是应该“在文档中”还是只是“在标题的注释中”，因为更改一个与更改另一个一样容易。所以一切都在文档中。

2) 用户不太可能一开始就去阅读您的头文件，因为他们可以有理由相信所有感兴趣的内容都在文档中。但即使他们是“我不相信文档，我阅读代码”类型的顽固分子，他们仍然会看到您希望他们看到的一切。

自动生成的 API 文档的缺点是它们可能是搜索的噩梦，因此 IMO 值得付出额外的努力来编写真正好的“介绍性”文档。这可能是也可能不是生成的 API 文档的一部分，具体取决于您的喜好。对于一个小的 API，只需按照“逻辑”而非字母顺序或源代码顺序列出所有函数，根据它们的用途而不是它们的作用进行描述，可以使其更容易进入 API 文档。通过“逻辑”，我的意思是首先列出常用函数，按照客户端调用它们的顺序，将“做相同类型的事情”(例如套接字的 send 和 sendTo)的备选方案组合在一起。然后列出不太常用的功能，最后列出高级用户和不寻常用例的晦涩内容。

该方法的一个主要困难(可能会成为阻碍)是，根据您的组织，您可能有一个文档团队，他们可能无法编辑标题。最好的情况是他们复制编辑你所做的事情，然后你进行更改并反馈。最坏的情况是整个想法陷入停顿，因为“只有文档团队应该编写面向客户的文档，并且它必须采用标准格式，而我们不能让 Doxygen 输出那种格式”。

至于“你还应该考虑什么”——你已经说过你会遵循最佳实践，所以很难再补充太多:-)