使用 PyCharm 在文档字符串中记录 Python 参数 [英] Documenting Python parameters in docstring using PyCharm

问题描述

我在找出在 Pycharm 中记录方法以实现类型提示和参数描述的正确方法时遇到了一些麻烦.

在

(2) 如果我切换到以 @ 符号开头，我会得到一个参数及其类型的列表，但我没有得到参数描述:

(3) 如果我坚持使用 @ 符号并删除类型，我会得到参数描述:

(4) 如果我为每个 @param 明确添加 @type(这完全炸毁了注释块的大小)，一切正常(但我讨厌评论的大小):

(5) 最后，为了完整起见，使用 : 而不是 @ 会导致所有内容都无法填充:

请注意，我曾尝试更改 Pycharm 中的文档系统，但它不会影响它呈现文档的方式——它似乎只影响它为您自动填充注释块的方式.

如何实现接近于示例 (1) 的文档，它是紧凑的，但实际上让它正确地填充了函数定义?我不想被风格束缚 (4).

解决方案

Have you check Settings... - Tools - Python 集成工具 - 文档字符串格式?您可以选择解析样式.

您可以选择:

• 普通
• Epytext
• 重构文本
• 麻木
• 谷歌

I'm having some trouble figuring out the proper way to document a method in Pycharm to achieve type hints AND parameter description.

In Pycharm's documentation it suggests:

:param "type_name" "param_name": "param_description"

(1) However, when I try to use that, the function definition does not properly show the parameter description:

(2) If I switch to leading with the @ sign I get a list of parameters and their types, but I do not get the parameter description:

(3) If I stick with the @ sign and drop the types, I get the parameter descriptions:

(4) If I explicitly add @type for each @param (which completely blows up the size of the comment block), everything works properly (but I hate the size of the comment):

(5) Finally, for sake of completeness, using : instead of @ causes everything to fail to populate:

Note that I have tried changing the documentation system within Pycharm, but it doesn't affect how it renders the documentation -- it only seems to affect how it autopopulates a comment block for you.

How can I achieve documentation as close to example (1) which is compact, but actually have it populate the function definition properly? I'd hate to be stuck with style (4).

解决方案

Have you checked Settings... - Tools - Python integrated tools - Docstring format? You can choose the parsing style.

You can choose from:

• Plain
• Epytext
• reStructuredText
• Numpy
• Google

这篇关于使用 PyCharm 在文档字符串中记录 Python 参数的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！