我需要创建一个API，允许我的客户的开发人员使用将作为库发布的专有C模块（想想.lib或.so - 不是来源）。
我希望尽可能使标题符合开发人员（因此我不需要），遵循最佳做法并提供说明，示例，警告，等的注释。
我还应该从业务，技术和普通常识的角度考虑什么？
谢谢！
答案 0 :(得分：4)
一种选择是使用（例如）Doxygen从头文件生成API文档。显然，你仍然会将文档与代码一起发送。
这给你带来两个好处：
1）你不必过于担心某些东西应该是“在文档中”还是只是“在标题中的注释中”，因为改变一个就像改变另一个一样容易。所以一切都在文档中。
2）用户不太可能首先阅读您的头文件，因为他们可以合理地确信所有感兴趣的内容都在文档中。但即使他们顽固不化“我不相信文档，我也会阅读代码”类型，然后他们仍然会看到你希望他们看到的所有内容。
自动生成的API文档的缺点是它们可能成为搜索的噩梦，所以IMO值得投入额外的精力来编写真正好的“入门”文档。这可能是也可能不是生成的API文档的一部分，具体取决于您的喜好。对于一个小型API，只需按照“逻辑”而不是按字母或源顺序列出所有功能的列表，根据它们为而不是它们所做的来描述，可以使它更容易进入API文档。通过“逻辑”，我的意思是首先列出常用函数，按照客户端调用它们的顺序，将“做同样的事情”（例如send和sendTo for socket）组合在一起。然后列出不太常用的函数，最后列出高级用户和不寻常用例的模糊内容。
这种方法的一个主要难点，可能是一个显示阻碍，是根据您的组织，您可能有一个文档团队，他们可能无法编辑标题。最好的情况是，他们复制 - 编辑你已完成的工作，然后进行更改并反馈。最糟糕的情况是整个想法停滞不前，因为“只有文档团队应该编写面向客户的文档，并且它必须采用标准格式，并且我们不能使Doxygen输出格式化”。
至于“你还应该考虑什么” - 你已经说过你会遵循最佳实践，所以很难添加很多： - ）
答案 1 :(得分：4)
其他人提到了文档问题，所以我会远离那些:-P。首先，确保你有理智的包括警卫。我个人倾向于：
FILENAME_20081110_H_，基本上是所有大写字母中的文件名，然后是完整日期，这有助于确保它足够独特，即使树中有另一个具有相同名称的标题。 （例如，您可以想象两个config.h包含在2个不同的lib目录中，其中包含使用CONFIG_H_或类似内容的警卫，从而产生冲突。无论您选择什么，只要它是可能是独特的。
此外，如果任何机会在c ++项目中使用此标头，请将标题包装在以下块中：
#ifdef __cplusplus
extern "C" {
#endif
/* your stuff */
#ifdef __cplusplus
}
#endif
这样可以节省一些带有名称重整问题的麻烦，并使它们不必在外部用这些包裹它们。
答案 2 :(得分：4)
请相当请确保您没有（重新）定义可能在其他地方定义的符号。我并不仅仅指标准名称，请在公共标题中声明/定义的所有符号前缀为特定字符串，并避免任何其他人可能曾经使用的任何名称。
我在“专业”公开标题中看到太多疯狂之后说出这个：
typedef unsigned short uchar;
答案 3 :(得分：3)
头文件本身应该干净整洁，可能接近最小。它应指向可以找到文档的位置。它可能不应该包含完整的示例（尽管我自己的一些标题可以做到这一点）。它应包括有关版权和许可的基本信息以及作者详细信息。它应该只包含最终用户需要的东西 - 只有开发人员需要的东西。它应该是独立的;它应该包含使其工作所需的任何其他头文件（因此用户可以编写'#include "your-header.h"'并且代码将干净地编译，即使这是他们包含的第一个或唯一的头文件。）
已添加：标题也应包含一些基本版本信息（文件修订号和修改日期，和/或产品发布版本号和发布日期）。这有助于人们查看该软件的两个版本 - 并且成功的软件不止一次发布。
已添加：Adam要求我展开“并没有只有开发人员需要的东西”。这意味着，例如，即使内部函数可能使用某种结构类型，如果没有外部接口使用该结构类型，则公共头不应包含该结构类型的定义。它应该位于未分发的私有头中（或仅与完整源一起分发）。它不应该污染公共标题。人们很容易说“但它只是浪费了一点点空间”，这是准确的，但如果每个人都浪费一点时间和空间，那么总浪费可能变得昂贵。
关于公共标题的关键点在于它应该包含库的用户（函数集）所需的所有内容，以及它们不需要的任何东西。
答案 4 :(得分：2)
考虑实际编写单独的文档。我认为man / info页面提供了一个很好的例子，说明API文档应该是什么样的。
答案 5 :(得分：1)
除了任何船只之外，考虑将文档放在网上，并将URL放在标题中。这将允许一些维护程序员在未来几年内访问文档，即使原件已丢失。