How does vs code get intellisense hints from python comments?

Question

I am seeing that VS Code is getting intellisense hints from the comments I put in my class functions:

 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 """

Which gives me a really nice popup when I use that function:

As you can see here, since I am about to enter the first parameter, desiredHeading, the intellisense was smart enough to know that the line in the comments under "Parameters" that starts with the variable name should be the first thing displayed in the hint. And indeed, once I type the first parameter and a comma, the first line of the intellisense popup changes to show the information about desiredDistance.

But I would like to know more about how the comments should be written. I read about the numpy style guide as being close to a standard most widely adopted, but when I change the parameter documentation format to match numpy (and somethihng called Sphinx has something to do with this too, I think), the popups were not the same. Really, I just want to see the documentation on how to document (yikes.) my python code so it renders correct intellisense, For example? how can I bold a word in the middle of a sentence? Are there other formatting options available

This is just for a middle-school robotics club, nothing like production code for real programmers. Nothing is broken, I just want to learn more about how this works.

Answer 1

That's it for docstrings in python, about it's introduction:

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

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

In addition, you can use the type stub of the parameter in this way.

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