Language agnostic 动态类型语言中的文档

一个简单的问题：在动态语言中记录函数参数或返回值类型的最佳方法是什么？在每个函数定义之后添加注释？

Python在函数定义之后使用注释，而MATLAB在函数定义之后使用注释

def fibo_gen(): 
    '''Generate Fibonacci numbers; return an iterator''' 
    x, y = 0, 1 
    while True: 
       yield x 
       x, y = y, x + y

和Matlab

function addtwo(x,y)
%  addtwo(x,y)  Adds two numbers, vectors, whatever, and
%               print the result = x + y
x+y

---

我不熟悉其他动态语言。这被认为是恰当的注释约定，在两个示例中都与help函数一起使用

这些约定更多地依赖于语言的注释/文档特性，而不是语言的静态/动态类型特性。它们更依赖于所使用的文档工具，因为一种语言通常有多个不同的文档工具。尽管在静态类型语言中，您不必记录参数的技术类型，但仍然需要记录其含义和用途

大量使用C派生语法的语言使用Javadoc风格的注释。例如，在PHP中：

/**
 * Calculates the area of circle.
 * @param float $radius The radius of circe.
 * @return float The area
 */
function area($radius) {

Ruby的YARD工具使用类似的约定：

# Calculates the area of circle.
# @param [Number] radius The radius of circe.
# @return [Number] The area
def area(radius)

我想总的来说，这是最主流的风格

在几种语言中，当您需要记录参数列表时，您只需编写几乎自由形式的注释，使用项目符号列表等。这方面一个有趣的例子是Perl及其pod注释：

=item stuff(radius)

Calculates the area of circle.

=cut

sub stuff {

与ralu提供的示例相反，我认为在函数定义之前有文档更常见。。。但最终这一切都取决于语言