python 文字列ドキュメンテーションはなんのために書くのか、文字列リテラルとは何か教えてほしい

Question

質問の経緯

https://docs.python.org/ja/3.11/tutorial/controlflow.html#defining-functions
のサイトの4.7. 関数を定義するを読んでいたところ文字列リテラルと文字列ドキュメンテーションについて出てきてわからなかったため質問しました。

質問の詳細

文字列ドキュメンテーションとは

def my_function():
... """Do nothing, but document it.
...
... No, really, it doesn't do anything.
... """
... pass
...

の"""~
"""
の最初の文字が大文字でピリオドで終わるこれのことでしょうか？
また関数がないのですが、なんのために使われるのでしょうか？

---

また、文字列リテラルとは''で囲まれたもののことでしょうか？
サイト：https://docs.python.org/ja/3/reference/lexical_analysis.html#literals

環境

python3.9.5
エディタ：vscode
os:windows10```ここに言語を入力
コード

Answer 1

• 文字列ドキュメンテーションとは

ドキュメンテーション文字列のことですね。

もしも、あなたがsumという関数のことを知りたいと思ったとしましょう。
そのとき、以下のようにして、関数sumのドキュメンテーション文字列を読むことができます。

>>> print(sum.__doc__)
Return the sum of a 'start' value (default: 0) plus an iterable of numbers

When the iterable is empty, return the start value.
This function is intended specifically for use with numeric values and may
reject non-numeric types.

同じように、

>>> print(my_function.__doc__)
Do nothing, but document it.

    No, really, it doesn't do anything.

を表示することができます。

• python 文字列ドキュメンテーションはなんのために書くのか

あなたが書いたモジュールやクラスや関数を、未来のあなた自身を含むそれらの機能の利用者に簡単に表示することができるオンラインマニュアルを提供するために書きます。

• また関数がないのですが、なんのために使われるのでしょうか？

関数はあります。本体がpassだけなので何もしません。
その動きを知りたければ以下を読んでください。

>>> print(my_function.__doc__)
Do nothing, but document it.

    No, really, it doesn't do anything.

• 文字列リテラルとは''で囲まれたもののことでしょうか？

プログラミング言語一般でリテラルというものがあります。
リテラルを読んでください。
Pythonの文字列リテラルは、2.4. リテラルで拡張BNFを使って定義されているものです。
stringprefixで始まり、'で挟まれていたり、”で挟まれていたり、’’’で挟まれていたり、”””で挟まれていたり、いろいろなものがあります。

Comments

[gagagalu]

下のように""" ~"""は必要ないのでしょうか？
参照:https://docs.python.org/ja/3.11/tutorial/controlflow.html#tut-docstrings
「4.8.7. ドキュメンテーション文字列」

def my_function():
... """Do nothing, but document it.
...
... No, really, it doesn't do anything.
... """
... pass
...
>>> print(my_function.__doc__)
Do nothing, but document it.

No, really, it doesn't do anything.

[ppaul]

~が何なのかがわからないという意味でしょうか？もしそうなら

Do nothing, but document it.改行
改行
No, really, it doesn't do anything

が~に当たるものです。ということです。

[gagagalu]

すいません。わかりにくかったですね。ドキュメンテーション文字列に"""はサイトのように必要ないのでしょうか？

[ppaul]

一般的な回答として、ドキュメンテーション文字列は文字列であればなんでも良いので"三つとか'三つでなくても問題ありません。
関数定義をするときにドキュメンテーション文字列が必須であるということはありません。
しかし、お知りになりたいことは、そのどちらでもないような気はしています。

サイトのドキュメンテーション文字列には"""があるが、それは必ずしも必要ないのか、という質問にも読めるし、
サイトのドキュメンテーション文字列には"""はないが、それと同様に必要ないのか、という質問なのか、それ以外の何かを聞いているのかがよくわかりません。

[gagagalu]

サイトのドキュメンテーション文字列には"""があるが、それは必ずしも必要なのか、という質問です。すいません。

Answer 2

ドキュメンテーション文字列(doc string)

関数やクラスの定義の先頭に文字列を記述するとドキュメンテーション文字列として扱われることになっています。これはpython言語の仕様です。
プログラミングでは、関数やクラスを定義するときに、その説明を書く習慣があります。説明が書いてあれば、他の人や未来の自分に役にたちます。他の言語では、作法として関数定義の前にコメントの形で付けるようになっていたりします。

文字列リテラル

リテラルとは、一般的にそのオブジェクトを直接表す方法のことです。
pythonでは、文字列は「'」や「"」や「'''」などで囲ったもの、リストであれば「[]」でくくってカンマで区切ったものなどあります。 数値についても、10進数は直接数字で書けますが、2進数であれば「0x101010」のように表わしたり、「3.14e-10」のような指数表記もできます。

データにはリテラルが無いものもあって、そういうものは、コンストラクタに渡して生成するなどします。setはVer.2.7以前はリテラル表現はありませんでした。

Answer 3

pythonで文字列を処理する必要がある場合には、文字列リテラルを記述します。
まあ、あなたが文字列を処理することはありえない、と言うならその必要はないんでしょうけど