Docstring

Programming languages that support docstring include Python, Lisp, Elixir, Clojure, Gherkin, Julia and Haskell. Tools that leverage docstring text include cobra-doc (Cobra), doctest (Python), Pydoc (Python), Sphinx (Python).

Examples

Elixir

Documentation is supported at language level, in the form of docstrings. Markdown is Elixir's de facto markup language of choice for use in docstrings:

<span id="mwMQ"></span><span class="kd" id="mwMg">def</span><span class="w" id="mwMw"> </span><span class="n" id="mwNA">module</span><span class="w" id="mwNQ"> </span><span class="nc" id="mwNg">MyModule</span><span class="w" id="mwNw"> </span><span class="k" id="mwOA">do</span> <span class="w" id="mwOQ"> </span><span class="na" id="mwOg">@moduledoc</span><span class="w" id="mwOw"> </span><span class="sh" id="mwPA">"""</span> <span class="w" id="mwPQ"> </span><span class="sh" id="mwPg">Documentation for my module. With **formatting**.</span> <span class="w" id="mwPw"> </span><span class="sh" id="mwQA">"""</span> <span class="w" id="mwQQ"> </span><span class="na" id="mwQg">@doc</span><span class="w" id="mwQw"> </span><span class="s2" id="mwRA">"Hello"</span> <span class="w" id="mwRQ"> </span><span class="kd" id="mwRg">def</span><span class="w" id="mwRw"> </span><span class="n" id="mwSA">world</span><span class="w" id="mwSQ"> </span><span class="k" id="mwSg">do</span> <span class="w" id="mwSw"> </span><span class="s2" id="mwTA">"World"</span> <span class="w" id="mwTQ"> </span><span class="k" id="mwTg">end</span> <span class="k" id="mwTw">end</span>

Lisp

In Lisp, a docstring is known as a documentation string. The Common Lisp standard states that a particular implementation may choose to discard docstrings. When they are kept, docstrings may be viewed and changed using the DOCUMENTATION function. For instance:

<span id="mwWQ"></span><span class="w" id="mwWg"> </span><span class="p" id="mwWw">(</span><span class="nb" id="mwXA">defun</span><span class="w" id="mwXQ"> </span><span class="nv" id="mwXg">foo</span><span class="w" id="mwXw"> </span><span class="p" id="mwYA">()</span><span class="w" id="mwYQ"> </span><span class="s" id="mwYg">"hi there"</span><span class="w" id="mwYw"> </span><span class="no" id="mwZA">nil</span><span class="p" id="mwZQ">)</span> <span class="w" id="mwZg"> </span><span class="p" id="mwZw">(</span><span class="nb" id="mwaA">documentation</span><span class="w" id="mwaQ"> </span><span class="nf" id="mwag">#'</span><span class="nv" id="mwaw">foo</span><span class="w" id="mwbA"> </span><span class="ss" id="mwbQ">'function</span><span class="p" id="mwbg">)</span><span class="w" id="mwbw"> </span><span class="nv" id="mwcA">=></span><span class="w" id="mwcQ"> </span><span class="s" id="mwcg">"hi there"</span>

Python

In Python, a docstring is a string literal that follows a module, class or function definition. It must be nothing but a string literal, not any other kind of expression. The docstring is accessible via the associated code element's __doc__ attribute and the help function.

The following Python code declares docstrings for each program element:

<span id="mweg"></span><span class="sd" id="mwew">"""The module's docstring"""</span> <span class="k" id="mwfA">class</span><span class="w" id="mwfQ"> </span><span class="nc" id="mwfg">MyClass</span><span class="p" id="mwfw">:</span> <span class="w" id="mwgA"> </span><span class="sd" id="mwgQ">"""The class's docstring"""</span> <span class="k" id="mwgg">def</span><span class="w" id="mwgw"> </span><span class="nf" id="mwhA">my_method</span><span class="p" id="mwhQ">(</span><span class="bp" id="mwhg">self</span><span class="p" id="mwhw">):</span> <span class="w" id="mwiA"> </span><span class="sd" id="mwiQ">"""The method's docstring"""</span>

If saved as mymodule.py, the following is an interactive session showing how the docstrings may be accessed:

<span id="mwjw"></span><span class="gp" id="mwkA">>>> </span><span class="kn" id="mwkQ">import</span><span class="w" id="mwkg"> </span><span class="nn" id="mwkw">mymodule</span> <span class="gp" id="mwlA">>>> </span><span class="n" id="mwlQ">help</span><span class="p" id="mwlg">(</span><span class="n" id="mwlw">mymodule</span><span class="p" id="mwmA">)</span> <span class="go" id="mwmQ">The module's docstring</span> <span class="gp" id="mwmg">>>> </span><span class="n" id="mwmw">help</span><span class="p" id="mwnA">(</span><span class="n" id="mwnQ">mymodule</span><span class="o" id="mwng">.</span><span class="n" id="mwnw">MyClass</span><span class="p" id="mwoA">)</span> <span class="go" id="mwoQ">The class's docstring</span> <span class="gp" id="mwog">>>> </span><span class="n" id="mwow">help</span><span class="p" id="mwpA">(</span><span class="n" id="mwpQ">mymodule</span><span class="o" id="mwpg">.</span><span class="n" id="mwpw">MyClass</span><span class="o" id="mwqA">.</span><span class="n" id="mwqQ">my_method</span><span class="p" id="mwqg">)</span> <span class="go" id="mwqw">The method's docstring</span>