Мне известен синтаксис, используемый для создания строки документации для стиля Google, такой как:
def function_with_types_in_docstring(param1, param2):
"""Example function with types documented in the docstring.
`PEP 484`_ type annotations are supported. If attribute, parameter, and
return types are annotated according to `PEP 484`_, they do not need to be
included in the docstring:
Args:
param1 (int): The first parameter.
param2 (str): The second parameter.
Returns:
bool: The return value. True for success, False otherwise.
"""
Однако, что если у меня есть функция, которая может возвращать несколько типов в зависимости от того, какая ветвь кода являетсяказнят?Как правильно документировать это?
Пример ниже.Что следует поместить в часть Returns?
def foo(x, y):
"""Dummy function.
Args:
x (int): integer
y (int): integer
Returns:
list/dict: either list or a dict depending on...
"""
if x > y:
return [1, 2, 3]
if x < y:
return {1:2}
Существует пример , который показывает два различных возможных типа возврата:
def add2(a, b):
"""Add numbers or concatenate strings.
Args:
a (int/str): String or integer to be added
b (int/str): String or integer to be added
Returns:
int/str: Result
"""
pass
Однако яИнтересно, что было бы лучшим способом предоставить оба типа и описание, чтобы Наполеон поддерживал его нативно, и было бы легко читать документы.
Использование int/str: %description% - единственный способобрабатывать несколько типов возврата?
Returns:
int/str: integer if a > b and a string otherwise