所以我已经有点习惯了 Javadoc 风格的文档。通过查看 Python 代码的各种示例，我发现，乍一看，文档似乎缺少很多信息。
好处：您很少看到不言自明的文档。文档字符串通常是一段或更少的英文标记，它们集成在一起，而不是在单独的行中突出。
坏处：结合 Python 的鸭子类型，我发现许多函数不清楚它们所期望的参数。没有类型提示（duck-hinting？），并且通常最好知道参数应该是类似列表的、类似字符串的、类似流的。
当然，Javadoc 是为较低级别的语言设计的，没有 Python 的强大自省能力，这可能解释了不那么冗长的文档理念。
关于 Python 文档标准和最佳实践的任何建议？
reStructuredText格式是为了响应可以嵌入到文档字符串中的 Python 文档的需求而设计的，因此最好的方法是学习reST 并使用该格式格式化您的文档字符串。您可能会发现，就像我所做的那样，然后您继续在 reST中格式化几乎所有文档，但这是一个侧面 :-)
为了专门记录您的 Python 代码，Sphinx系统是一组对 reST 格式的扩展，以及用于呈现文档的构建系统。由于它旨在记录 Python 本身，包括标准库，因此Sphinx 允许对源代码进行结构良好的文档，当然包括您所要求的函数签名的细节。它允许构建一个全面的文档套件，包括自动提取和手写，所有这些都使用相同的格式化系统。
如果您只想从源代码生成文档，那么Epydoc将从您的源代码中提取 API 文档；它也读取文本的 reST 格式。