В одном проекте, доставшемся "по наследству", написанному на фреймворке FastAPI (если это имеет значение), имеется более тысячи строк едва документированного кода, все в одном файле (!). Понятное дело, в этой мешанине трудно ориентироваться и хочется начать с автодокументации кода. Я имею в виду не просто генерацию названия функций с их сигнатурами, а больше про то какое у них предназначение. А для этого, насколько я понимаю, нужно использовать ИИ модели, понимающие код и умеющие делать подытоживание.
Пробовал Sphinx расширение AutoAPI, но оно не решает саму проблему с отсутствующими комментариями. А мне очень важно, чтобы хотя бы вкратце функции и методы говорили об их предназначении.
В общем, исходя из возможностей инструментов автодокументирования, прихожу к выводу, что они не умеют делать вышесказанного. Или я не прав?
Пример исходного кода:
def get_docs_time_range(docs: list[DTOStatus]) -> tuple[datetime, datetime]:
dates = [doc.created_at_timestamp for doc in docs]
dates.sort()
earliest = dates[0]
latest = dates[-1]
return (earliest, latest)
Желаемый результат:
def get_docs_time_range(docs: list[DTOStatus]) -> tuple[datetime, datetime]:
"""
Returns the earliest and latest timestamp from the given list of DTOStatus objects.
Args:
docs (list[DTOStatus]): A list of DTOStatus objects containing the timestamps to analyze.
Returns:
tuple[datetime, datetime]: A tuple containing the earliest and latest timestamps from the input list.
"""
dates = [doc.created_at_timestamp for doc in docs]
dates.sort()
earliest = dates[0]
latest = dates[-1]
return (earliest, latest)
