ドキュメンテーション文字列のparamについて

Question

プログラミング初心者でpythonを独学で学んでいるものです。
参考書に以下のように書かれていました。

def add(x, y):
"""
Returns x + y.
:param x: int.
:param y: int.
:return: int sum of x and y.
"""
return x + y

この中で"""に挟まれた部分がドキュメンテーション文字列で、:return: int sum of x and y.は戻り値について説明していることは分かりますが、paramがどのような意味なのか知りたいです。また、Returnsと複数形になっているのは、なぜなのか知りたいです。

Answer 1

ドキュメンテーション文字列 というのは、基本的には何をどのように書いてもいいのですが、特定の書式に沿って書くと、

• IDEやエディタでその情報を使ってヒントや候補を出してくれたりする
• Sphinxなどのドキュメント生成ツールを利用できる
• そのコードを読む他人や未来の自分の役に立つ

などの利益が得られます。

例にあるコードはreStructuredTextという書式で書かれているようですが、型の情報が無くて、説明の部分に型が書いてあるなど、よく見る書きかたとは違うかきかたをしているようです。

プログラムの書き方全般について言えることですが、文法的に間違えていなければ、比較的自由に掛けるものなので、いろいろなソースコードを見てどのように書いてあるか調べてみたり、ドキュメンテーション文字列のように、開発の助けになるような機能/仕組みもいろいろあるので、触れたときに調べてみるといいと思います。

Answer 2

「python docstring」でググるとよくわかるのではないでしょうか。
手っ取り早くは、以下をオススメします。

https://note.nkmk.me/python-docstring/

Answer 3

paramは日本語で引数の意味です。
Returnsは単に動詞で、Returns x + yで「この関数はx+yを戻り値として返します。」と言う
関数ドキュメンテーションの一部です。