VS Code从Python注释生成IntelliSense提示的规则与编写规范

VS Code默认搭载的Python语言支持组件，会自动解析函数的三引号文档字符串，提取内容生成智能提示，对多种常见注释格式都做了适配，不同格式的解析完整度略有区别。

适配现有使用习惯的稳定写法 #

你目前使用的简化类Google风格注释，是识别稳定性最高、写起来最省事的格式，你观察到的参数提示随光标位置自动切换的效果，就是组件正确解析了注释结构的表现。固定写法直接套用即可：

• 函数定义下第一行写三个双引号开头，先写函数的功能说明，需要分段直接空一行即可
• 参数说明段固定以Parameters作为标题，下一行写长度相近的横线做分隔（你现在用的-------------就符合要求，长度略有差异不影响识别）
• 每个参数单独成块，第一行固定为参数名: 该参数的核心作用说明，后面可以换行追加自定义说明项，比如你现在写的type（参数类型）、values（取值范围）、default（默认值），所有和该参数相关的内容都会被归类到对应参数的提示内容中
• 示例段固定以Example作为标题，下一行加横线分隔，直接放调用示例代码即可，代码会自动以代码格式渲染在提示弹窗中

你之前写的示例就是符合要求的正确写法，直接沿用即可：

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

    """

对应的智能提示效果如下：

NumPy风格注释显示异常的原因 #

NumPy风格文档对格式要求更严格，要求参数名和类型必须写在同一行用冒号分隔，后续说明必须保持固定缩进，比如：

Parameters
----------
desiredHeading : float
    On what heading should the robot drive
    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

如果缩进不对、参数名和类型的写法不符合要求，解析组件就无法将参数和说明内容一一对应，就会出现提示不随光标切换、内容错乱的问题。对初中机器人俱乐部的使用场景来说，你现在用的简化格式容错率更高，不需要严格对齐缩进，更适合学生使用，没必要强行更换NumPy风格。

注释支持的文本格式 #

注释内容支持基础Markdown语法，常用格式如下：

• 文字加粗：用**要加粗的内容**包裹，提示中就会显示为粗体
• 文字斜体：用*要斜体的内容*包裹
• 行内代码：用反引号`内容`包裹，适合标记参数名、其他函数名等内容，显示会更清晰
• 多行代码块：用三个反引号包裹代码段，和你写Python代码块的格式一致
• 无序列表：每一行开头加-，就会渲染为列表格式
• 分段：注释里空一行就会在提示中显示为分段，行尾加两个空格再回车可以实现强制换行

场景使用建议 #

不需要刻意追求专业生产环境的复杂文档规范，只要把函数作用、参数要求、注意事项写清楚，学生调用函数时能通过提示看懂用法就足够，你当前的写法已经完全满足需求。

内容的提问来源于stack exchange，提问作者MrGibbage