vs code 如何从 python 评论中获得智能提示？

Question

我看到 VS Code 从我在 class 函数中的注释中得到了智能提示：

 def GyroDriveOnHeading(self, desiredHeading, desiredDistance): """ Drives the robot very straight on a given heading for a \ given distance, using the acceleration and the gyro. \ Accelerates to prevent wheel slipping. \ Gyro keeps the robot pointing on the desired heading. Minimum distance that this will work for is about 16cm. If you need to go a very short distance, use move_tank. Parameters ------------- desiredHeading: On what heading should the robot drive (float) type: float values: any. Best if the desired heading is close to the current heading. Unpredictable robot movement may occur for large heading differences. default: no default value desiredDistance: How far the robot should go in cm (float) type: float values: any value above 16.0. You can enter smaller numbers, but the robot will still go 16cm default: no default value Example ------------- import base_robot br = base_robot.BaseRobot() br.GyroDriveOnHeading(90, 40) #drive on heading 90 for 40 cm """

当我使用 function 时，这给了我一个非常好的弹出窗口：

正如你在这里看到的，因为我要输入第一个参数，desiredHeading，智能感知足够聪明，知道“参数”下注释中以变量名开头的行应该是提示中显示的第一件事. 事实上，一旦我输入第一个参数和一个逗号，智能感知弹出窗口的第一行就会更改以显示有关所需距离的信息。

但我想更多地了解应该如何写评论。 我读到 numpy 样式指南接近最广泛采用的标准，但是当我更改参数文档格式以匹配 numpy 时（我认为名为 Sphinx 的东西也与此有关），弹出窗口不是相同的。 真的，我只想查看有关如何记录（哎呀）我的 python 代码的文档，以便它呈现正确的智能感知，例如？ 如何在句子中间加粗一个单词？ 是否有其他可用的格式选项

这仅适用于中学机器人俱乐部，与真正的程序员的生产代码完全不同。 没有什么是坏的，我只是想了解更多关于它是如何工作的。

Answer 1

python 中的文档字符串就是这样，关于它的介绍：

https://docs.python.org/3.10/tutorial/controlflow.html#documentation-strings

https://peps.python.org/pep-0287/

此外，您可以通过这种方式使用参数的类型存根。

 def open(url: str, new: int =..., autoraise: bool =...) -> bool:...