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