Python文档跨函数参数引用规范及PyCharm集成方法

合理性说明 #

完全合理。当多个函数共享相同的参数定义（比如私有辅助函数复用主函数的参数规则），引用已有参数文档可以避免重复编写相同内容，提升文档的一致性和维护效率。

符合Python风格的引用方式 #

• 简洁文字说明：直接在参数描述中明确关联目标函数的参数，比如:param param1: 与main_function的param1参数定义一致，这种方式简单直观，无需额外工具支持。
• Sphinx交叉引用语法：如果使用Sphinx生成正式文档，可采用标准交叉引用格式，既符合Python生态的文档规范，又能支持工具跳转。格式为:param param1: 参见 :func:main_function 的 :paramref:main_function.param1``。
• Google风格docstring引用：若项目采用Google风格的docstring，可写成：

  Args:
      param1: Same as :func:`main_function`'s param1 argument.
  

适配PyCharm的集成方式 #

PyCharm对Python常见的docstring语法支持非常友好，推荐以下两种方式实现跳转：

1. 使用Sphinx交叉引用：PyCharm会自动识别:func:和:paramref:标记，按住Ctrl键点击即可直接跳转到main_function的param1参数文档，无缝集成开发流程。
2. 保持参数名一致：如果辅助函数的参数名与主函数完全匹配，PyCharm的代码提示功能会自动关联主函数的参数文档，在查看私有函数时可快速查看参数定义。

示例修改 #

def _private_func(param1):
    """
    辅助主函数完成核心逻辑的私有函数
    :param param1: 参见 :func:`main_function` 的 :paramref:`main_function.param1`
    """

def main_function(param1):
    """
    处理核心业务逻辑的主函数
    :param param1: 详细参数说明：用于指定待处理的数据源，支持字符串路径或列表类型的原始数据
    """

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