是否可将代码注释设为元数据，而非直接嵌入代码本身？

针对你希望把注释作为独立元数据、避免内嵌代码臃肿，同时保留IDE悬停时的文档展示需求，以下是几种可行的实现方式：

1. 利用__doc__属性动态注入外部文档 #

这是最轻量化的方案，无需额外插件，依赖Python原生的文档属性和Pylance的原生支持：

实现步骤： #

• 把函数/类的文档写在外部JSON/YAML文件中，比如function_docs.json：

{
  "add": {
    "docstring": "计算两个整数的和\n\n参数:\n    a (int): 第一个加数，需为整数类型\n    b (int): 第二个加数，需为整数类型\n返回:\n    int: 两个输入整数的求和结果"
  }
}

• 编写装饰器从外部文件加载文档并注入到函数的__doc__属性：

import json
from functools import wraps

def inject_doc(doc_file: str):
    """从外部文件注入文档到函数__doc__属性"""
    with open(doc_file, 'r', encoding='utf-8') as f:
        doc_map = json.load(f)
    
    def decorator(func):
        func.__doc__ = doc_map.get(func.__name__, "")
        @wraps(func)
        def wrapper(*args, **kwargs):
            return func(*args, **kwargs)
        return wrapper
    return decorator

# 使用装饰器，代码中仅保留类型注解
@inject_doc("function_docs.json")
def add(a: int, b: int) -> int:
    return a + b

• Pylance悬停函数时，会自动读取__doc__内容并展示，完全不影响代码的整洁性。

2. 使用typing.Annotated附加元数据注释 #

通过Annotated给类型注解附加文档元数据，配合Pylance的配置实现悬停展示：

from typing import Annotated, TypeVar

T = TypeVar('T')
# 自定义元数据类存储文档
class Doc:
    def __init__(self, desc: str):
        self.desc = desc

# 类型注解中附加文档元数据
def add(
    a: Annotated[int, Doc("第一个加数，必须为整数类型")],
    b: Annotated[int, Doc("第二个加数，必须为整数类型")]
) -> Annotated[int, Doc("返回两个整数的求和结果")]:
    return a + b

• 配置VS Code的settings.json，确保Pylance能识别并展示Annotated元数据：

{
  "python.analysis.typeCheckingMode": "strict",
  "python.analysis.displayAnnotations": "all"
}

• 悬停时Pylance会显示类型注解的同时，展示附加的Doc描述内容。

3. 外部文档文件+自定义IDE插件（适合大规模项目） #

如果需要统一管理所有代码的文档，可编写简单的VS Code插件：

• 维护一个结构化的文档库（如JSON/YAML），按模块+函数名的全路径映射文档内容；
• 插件监听IDE的悬停事件，识别当前代码元素的全路径，从文档库中匹配对应的内容并展示在悬停提示中。
  这种方式完全分离代码与文档，适合大型团队或多模块项目的文档统一维护。

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