未文档化的公共函数 (D103)
源自 pydocstyle 代码检查器。
作用
检查未文档化的公共函数定义。
为什么这不好？
公共函数应通过文档字符串进行文档化，以概述其目的和行为。
通常，函数文档字符串应描述函数的行为、参数、副作用、异常、返回值以及任何可能与用户相关的其他信息。
如果代码库遵循函数文档字符串的标准格式，请遵循该格式以保持一致性。
示例
def calculate_speed(distance: float, time: float) -> float:
try:
return distance / time
except ZeroDivisionError as exc:
raise FasterThanLightError from exc
改用 (使用 NumPy 文档字符串格式)
def calculate_speed(distance: float, time: float) -> float:
"""Calculate speed as distance divided by time.
Parameters
----------
distance : float
Distance traveled.
time : float
Time spent traveling.
Returns
-------
float
Speed as distance divided by time.
Raises
------
FasterThanLightError
If speed is greater than the speed of light.
"""
try:
return distance / time
except ZeroDivisionError as exc:
raise FasterThanLightError from exc
或者，使用 Google 文档字符串格式
def calculate_speed(distance: float, time: float) -> float:
"""Calculate speed as distance divided by time.
Args:
distance: Distance traveled.
time: Time spent traveling.
Returns:
Speed as distance divided by time.
Raises:
FasterThanLightError: If speed is greater than the speed of light.
"""
try:
return distance / time
except ZeroDivisionError as exc:
raise FasterThanLightError from exc