我有一个包含多个文件的C程序，例如，stuff.c实现了一些函数，而stuff.h则包含了这些函数的原型。
我该如何在注释中记录这些函数的文档？
应该将所有文档都放在头文件中，还是都放在.c文件中，或者将文档复制到两个文件中？我喜欢后一种方法，但是我会遇到问题，即我会更新其中一个文件的文档，而忘记更新另一个文件（通常是我首先修改的文件，例如如果我首先修改头文件，则它的注释将反映出这一点，但如果我更新实现，则只有那些注释会更改）。
对于C++代码，此问题及其答案也适用——请参见 在哪里放置文档注释？
将函数使用者需要知道的信息放在头文件中。
将函数维护者需要知道的信息放在源代码中。
我喜欢遵循Google的C++样式指南。
其中写道：
函数声明
- 每个函数声明都应该紧接在其前面有一段注释，描述函数的作用和使用方法。这些注释应该是描述性的（“打开文件”），而不是命令式的（“打开文件”）；注释描述函数的功能，而不是告诉函数如何执行任务。一般来说，这些注释不应该描述函数如何执行任务，这应该留给函数定义中的注释。
函数定义
每个函数定义都应该有一个注释，描述函数的作用以及它如何完成任务的任何棘手的问题。例如，在定义注释中你可以描述你使用的任何代码技巧，概述你所经历的步骤，或者解释为什么你选择实现该函数的方式，而不是使用可行的替代方案。例如，你可能要提到为什么它必须在函数的前半部分获取锁，但为什么在后半部分不需要。
请注意，你不应该只是重复在函数声明中给出的注释，无论是在.h文件还是其他地方。可以简要地概述函数的作用，但注释的重点应该是如何实现它。
请考虑人们可能只有头文件和已编译的实现版本就能使用这些函数。确保在头文件中记录使用您的函数所需的任何内容。实现细节可以在源代码中记录。
头文件中的注释与实现文件应反映两者使用方式的不同。
如果您要创建接口文档（例如，要使用Doxygen提取的文档，与JavaDocs的一般顺序相同），则明显属于头文件。即使您不打算提取注释以生成单独的文档，也适用相同的一般思想 - 解释接口/如何使用代码的注释主要或仅属于头文件。
实现中的注释通常与实现相关。与频繁实践相反，大多数注释应该解释为什么做出特定的决策而不是尝试解释如何工作。当您做出有意义但可能不明显的决策时，这一点尤其正确（例如，指出您没有使用Quicksort，因为您需要一个稳定的排序）。
当你思考这个问题时，它其实很简单。
API文档必须放在头文件中。因为头文件定义了外部接口，所以API文档需要放在那里。
通常情况下，实现细节应该对API用户隐藏。包括实现文档（除非它可能影响使用，例如时间复杂度等）。因此，实现文档应该放在实现文件中。
永远不要在多个地方重复文档。这将难以维护，并且一旦有人不得不更改它，它就会失去同步。
