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

ドキュメンテーション文字列あるいはdocstring（英語: documentation string、ドックストリング）はプログラミングにおいてコメントのようにソースコードの特定の部分を文書化するための文字列リテラルのこと。通常のコメントやdocblockのように解析時に構文木から除外されず、プログラムの実行時まで保持されるため対話的なヘルプやメタデータとして利用できる。

歴史的にはEmacsの前身のTECOに初めて実装された^[1]。

docstringをサポートするプログラミング言語にはPython、Lisp、Elixir、Clojure^[2]、 Gherkin（英語版）^[3]、Julia^[4] and Haskell^[5]がある。

実装例[編集]

Elixir[編集]

言語レベルでドキュメンテーションがサポートされており、Markdownがデファクトのマークアップ言語として利用されている。

def module MyModule do
  @moduledoc """
  Documentation for my module. With **formatting**.
  """

  @doc "Hello"
  def world do
    "World"
  end
end

Lisp[編集]

Lispではdocstringとして知られる。Common Lisp標準において、処理系は必要に応じてdocstringを理由なくいつでも破棄してよいと定めている。docstringが温存されているとき、DOCUMENTATION関数^[6]で表示および変更できる。

 (defun foo () "hi there" nil)
 (documentation #'foo 'function) => "hi there"

Python[編集]

Pythonでは定義（defまたはclass）の直後の文に文字列リテラルを記述することでコードオブジェクト（モジュール、クラス、または関数）のdocstringになる。他のタイプの式ではなく、文字列リテラルでなくてはならない。コードオブジェクトのdocstringは、そのオブジェクトの__doc__属性およびhelp関数を介して利用できる。

以下のコードはPythonファイルでdocstringを宣言する。

"""The module's docstring"""

class MyClass:
    """The class's docstring"""

    def my_method(self):
        """The method's docstring"""

def my_function():
    """The function's docstring"""

上記のコードをmymodule.pyとして保存したとき、インタラクティブシェルで以下のようにdocstringにアクセスできる。

>>> import mymodule
>>> help(mymodule)
The module's docstring
>>> help(mymodule.MyClass)
The class's docstring
>>> help(mymodule.MyClass.my_method)
The method's docstring
>>> help(mymodule.my_function)
The function's docstring
>>>