从 Javadoc 迁移到 Python 文档
所以我已经有点习惯了 Javadoc 风格的文档。浏览 Python 代码的各种示例，我发现乍一看，文档似乎缺少很多信息。
好处是：你很少会看到不言而喻的文档。文档字符串通常是一段或更少的英文标记，它们集成在一起，而不是在单独的行上突出。
坏处：结合 Python 的鸭子类型，我发现许多函数都不清楚它们期望的参数。没有类型提示（鸭子提示？），而且很多时候最好知道参数应该是类似列表、类似字符串、类似流的。
当然，Javadoc 是为较低级语言设计的，没有 Python 那样强大的自省能力，这可能是其文档哲学不那么冗长的原因。
关于 Python 文档标准和最佳实践有什么建议吗？
So I've gotten somewhat used to Javadoc style documentation. Looking through various examples of Python code, I'm finding that, at first blush, the documentation seems to be missing a lot of information.
The good: vary rarely do you see self-evident bits of documentation. Docstrings are usually a paragraph or less of English markup that integrates instead of standing out on separate lines.
The bad: in conjunction with Python's duck-typing, I find that many functions are unclear about the parameters they expect. There's no type hinting (duck-hinting?) and often times it would be nice to have some idea that the parameter should be list-like, string-like, stream-like.
Of course, Javadoc was designed for a lower-level language, without great introspection abilities of Python, which might account for the less verbose documentation philosophy.
Any advice on Python documentation standards and best-practices?
如果你对这篇内容有疑问，欢迎到本站社区发帖提问 参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。
绑定邮箱获取回复消息
由于您还没有绑定你的真实邮箱，如果其他用户或者作者回复了您的评论，将不能在第一时间通知您！
发布评论
评论（1）
reStructuredText 格式是为了满足可以嵌入文档字符串中的 Python 文档的需求而设计的，所以最好的办法是学习休息并使用该格式格式化您的文档字符串。您可能会像我一样发现，然后继续在 reST 中格式化任何任何文档，但这是一个侧面:-)
为了专门记录您的 Python 代码，Sphinx 系统是一组对 reST 格式的扩展，也是一个用于渲染文档的构建系统。由于它旨在记录 Python 本身（包括标准库），Sphinx 允许提供结构良好的源代码文档，当然包括您所要求的函数签名的细节。它允许构建全面的文档套件，包括自动提取和手写，全部使用相同的格式化系统。
如果您只想从源代码生成文档，那么Epydoc将从您的源代码中提取 API 文档；它也读取文本的其余格式。
The reStructuredText format was designed in response to the need for Python documentation that could be embedded in docstrings, so the best thing is to learn reST and format your docstrings with that format. You might find, as I did, that you then go on to format just about any documentation in reST, but that's a side point :-)
For specifically documenting your Python code, the Sphinx system is a set of extensions to the reST format, and a build system for rendering documents. Since it was designed to document Python itself, including the standard library, Sphinx allows for very well-structured documentation of source code, including of course the specifics of function signatures as you're asking. It allows a comprehensive documentation suite to be built, both auto-extracted and hand-written, all using the same formatting system.
If you only want documentation generated from your source code, then Epydoc will extract API documentation from your source code; it, too, reads reST formatting for the text.