{{Short description |String literal that provides documentation per computer programming language syntax}} A '''docstring''' is a string literal that annotates an associated section of source code. It provides for the same utility as a comment, but unlike a comment is a string literal and is retained as part of the running program. Some development tools display docstring information as part of an interactive help system.
Programming languages that support docstring include Python, Lisp, Elixir, Clojure,<ref>{{Cite web |url=https://clojure.github.com/clojure/clojure.core-api.html#clojure.core/defn |title=Function definition with docstring in Clojure |access-date=2017-09-20 |archive-date=2013-01-29 |archive-url=https://web.archive.org/web/20130129013007/http://clojure.github.com/clojure/clojure.core-api.html#clojure.core/defn |url-status=dead }}</ref> Gherkin,<ref>{{Cite web |url=https://cucumber.io/docs/reference#gherkin |title=Step Arguments - Doc Strings |access-date=2016-06-22 |archive-url=https://web.archive.org/web/20160131200855/https://cucumber.io/docs/reference#gherkin |archive-date=2016-01-31 |url-status=dead }}</ref> Julia<ref>{{cite web |url=http://docs.julialang.org/en/stable/manual/documentation/ |title=Documentation — Julia Language 0.4.1 documentation |website=docs.julialang.org |url-status=dead |archive-url=https://web.archive.org/web/20151117020229/http://docs.julialang.org/en/stable/manual/documentation/ |archive-date=2015-11-17}} </ref> and Haskell.<ref>{{Cite web|url=https://hackage.haskell.org/package/docstrings|title = Docstrings}}</ref> 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: <syntaxhighlight lang="elixir"> def module MyModule do @moduledoc """ Documentation for my module. With **formatting**. """
@doc "Hello" def world do "World" end end </syntaxhighlight>
===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.<ref>[http://www.lispworks.com/documentation/HyperSpec/Body/f_docume.htm CLHS: Standard Generic Function DOCUMENTATION...]</ref> For instance: <syntaxhighlight lang="lisp"> (defun foo () "hi there" nil) (documentation #'foo 'function) => "hi there" </syntaxhighlight>
===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 <code>__doc__</code> attribute and the <code>help</code> function.
The following Python code declares docstrings for each program element:
<syntaxhighlight lang="python"> """The module's docstring"""
class MyClass: """The class's docstring"""
def my_method(self): """The method's docstring""" </syntaxhighlight>
If saved as {{mono|mymodule.py}}, the following is an interactive session showing how the docstrings may be accessed:
<syntaxhighlight lang="pycon"> >>> import mymodule >>> help(mymodule) The module's docstring >>> help(mymodule.MyClass) The class's docstring >>> help(mymodule.MyClass.my_method) The method's docstring </syntaxhighlight>
==See also== * docblock {{endash}} Source code comment formatted for automated documentation generation * {{Annotated link |Literate programming}} * {{Annotated link |Plain Old Documentation}}
==References== {{Reflist}}
==External links== *[https://epydoc.sourceforge.net/docstrings.html Python Docstrings] at Epydoc's SourceForge page *[https://web.archive.org/web/20160303174051/http://www.linuxselfhelp.com/gnu/elisp/html_chapter/elisp_24.html#SEC361 Documentation in GNU Emacs Lisp] *[http://www.stack.nl/~dimitri/doxygen/docblocks.html#pythonblocks Section] from the doxygen documentation about Python docstrings
Category:Programming constructs Category:Lisp (programming language) Category:Python (programming language) Category:Source code documentation formats Category:String (computer science)