Почему документация по функции JavaScript находится за пределами функции?

Question

В JavaScript большинство форматов документации помещают блок над функцией:

/**
 * example JavaScript docstring
 */
function myFunction(){...}

(пример: JSDoc )

Однако в Python большинство форматов документации используют документацию внутри тело функции:

def my_function():
    """ Do amazing things
    """
    (function body here)

(пример: PEP 257 )

Исходя из фона Python, этот формат выглядит гораздо более практичным, потому что:

1. вам не нужно поддерживать все * звезд и их интервал
2. для генераторов документации проще разобраться, взяв тело функции
3. Сигнатура функции, естественно, становится «частью» документации, так как она тут же, и вы можете прочитать имя функции перед документами, не прокручивая вначале.

Почему принято размещать документы вне функции в JavaScript? Я предполагаю, что это пережиток старых языков, но я бы хотел более вескую причину, чем эта. Я надеюсь, что есть интересная историческая или практическая причина для этого. Просвети меня!

Answer 1

Это предпочтение разработчика, вы можете найти службы документации Python (например, doxygen ), у которых уже есть документация.

Однако у doxygen (довольно известного и старого документатора) есть место, где говорится, что языки стиля C (например, JS) должны иметь комментарии перед определениями в указанном вами стиле.

Answer 2

Формат, используемый в JS, взят из языка Си, так как многострочные комментарии поддерживаются "из коробки", что облегчает задачу.

Принимая во внимание, что Python не имеет многострочных комментариев (только однострочные), поэтому становится проще просто использовать строки heredocs / verbatim в начале тела функции.

Имейте в виду, что это скорее эстетический выбор, чем технический, поэтому у него не обязательно есть четкое и ясное объяснение.