为什么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

JS中使用的格式来自该语言的C背景，因为开箱即用地支持多行注释，这使事情变得更容易。

Python没有多行注释（只有单行注释），因此在函数体的开头仅使用heredocs / verbatim字符串会变得更加简单。

请记住，它更多是一种美学选择，而不是技术选择，因此不一定有明确，明确的解释。

Answer 2

这是开发人员的偏爱，您可以找到之前有文档的Python文档服务（例如doxygen）。

但是，doxygen（一个非常著名的老文档）在一个地方说，C风格语言（如JS）应该在您指出的样式定义之前添加注释。