Основной поток, как уже указывалось в других ответах, вероятно, идет по пути Sphinx , чтобы вы могли использовать Sphinx для генерации этих причудливых документов позже.
При этом я лично иногда использую стиль встроенных комментариев.
def complex( # Form a complex number
real=0.0, # the real part (default 0.0)
imag=0.0 # the imaginary part (default 0.0)
): # Returns a complex number.
"""Form a complex number.
I may still use the mainstream docstring notation,
if I foresee a need to use some other tools
to generate an HTML online doc later
"""
if imag == 0.0 and real == 0.0:
return complex_zero
other_code()
Еще один пример с некоторыми мельчайшими подробностями, документированными в строке:
def foo( # Note that how I use the parenthesis rather than backslash "\"
# to natually break the function definition into multiple lines.
a_very_long_parameter_name,
# The "inline" text does not really have to be at same line,
# when your parameter name is very long.
# Besides, you can use this way to have multiple lines doc too.
# The one extra level indentation here natually matches the
# original Python indentation style.
#
# This parameter represents blah blah
# blah blah
# blah blah
param_b, # Some description about parameter B.
# Some more description about parameter B.
# As you probably noticed, the vertical alignment of pound sign
# is less a concern IMHO, as long as your docs are intuitively
# readable.
last_param, # As a side note, you can use an optional comma for
# your last parameter, as you can do in multi-line list
# or dict declaration.
): # So this ending parenthesis occupying its own line provides a
# perfect chance to use inline doc to document the return value,
# despite of its unhappy face appearance. :)
pass
Преимущества (как @ mark-horvath уже указывалось в другом комментарии):
- Самое главное, что параметры и их документ всегда остаются вместе, что дает следующие преимущества:
- Меньше ввода (нет необходимости повторять имя переменной)
- Более простое обслуживание при изменении / удалении переменной. После переименования какого-либо параметра никогда не будет какого-либо абзаца с документом о параметрах.
- и проще найти пропущенный комментарий.
Теперь некоторые могут подумать, что этот стиль выглядит "некрасиво". Но я бы сказал, «уродливый» - субъективное слово. Более нейтральный способ - сказать, что этот стиль не является мейнстримом, поэтому он может показаться вам менее знакомым и, следовательно, менее удобным. Опять же, «удобный» - это тоже субъективное слово. Но дело в том, что все преимущества, описанные выше, объективны. Вы не можете достичь их, если будете следовать стандартным путем.
Надеюсь, когда-нибудь в будущем появится инструмент для генерации документов, который также может использовать такой встроенный стиль. Это приведет к усыновлению.
PS: Этот ответ вытекает из моего собственного предпочтения использовать встроенные комментарии всякий раз, когда я считаю нужным. Я использую тот же встроенный стиль для документирования словаря тоже.