In
programming, a docstring is a
string literal
A string literal (computer programming), literal or anonymous string is a String (computer science), string value in the source code of a computer program. Modern Computer programming, programming languages commonly use a quoted sequence of charact ...
specified in
source code
In computing, source code, or simply code, is any collection of code, with or without comments, written using a human-readable programming language, usually as plain text. The source code of a program is specially designed to facilitate the wo ...
that is used, like a
comment
Comment may refer to:
* Comment (linguistics) or rheme, that which is said about the topic (theme) of a sentence
* Bernard Comment (born 1960), Swiss writer and publisher
Computing
* Comment (computer programming), explanatory text or informa ...
, to document a specific segment of code. Unlike conventional source code comments, or even specifically formatted comments like
docblocks, docstrings are not stripped from the source tree when it is parsed and are retained throughout the runtime of the program. This allows the programmer to inspect these comments at run time, for instance as an interactive help system, or as
metadata
Metadata is "data that provides information about other data", but not the content of the data, such as the text of a message or the image itself. There are many distinct types of metadata, including:
* Descriptive metadata – the descriptive ...
.
Languages that support docstrings include
Python
Python may refer to:
Snakes
* Pythonidae, a family of nonvenomous snakes found in Africa, Asia, and Australia
** ''Python'' (genus), a genus of Pythonidae found in Africa and Asia
* Python (mythology), a mythical serpent
Computing
* Python (pro ...
,
Lisp
A lisp is a speech impairment in which a person misarticulates sibilants (, , , , , , , ). These misarticulations often result in unclear speech.
Types
* A frontal lisp occurs when the tongue is placed anterior to the target. Interdental lisping ...
,
Elixir
ELIXIR (the European life-sciences Infrastructure for biological Information) is an initiative that will allow life science laboratories across Europe to share and store their research data as part of an organised network. Its goal is to bring t ...
,
Clojure
Clojure (, like ''closure'') is a dynamic and functional dialect of the Lisp programming language on the Java platform. Like other Lisp dialects, Clojure treats code as data and has a Lisp macro system. The current development process is comm ...
,
Gherkin
A pickled cucumber (commonly known as a pickle in the United States and Canada and a gherkin in Britain, Ireland, South Africa, Australia, and New Zealand) is a usually small or miniature cucumber that has been pickled in a brine, vinegar, or ...
,
Julia
Julia is usually a feminine given name. It is a Latinate feminine form of the name Julio and Julius. (For further details on etymology, see the Wiktionary entry "Julius".) The given name ''Julia'' had been in use throughout Late Antiquity (e.g ...
and
Haskell
Haskell () is a general-purpose, statically-typed, purely functional programming language with type inference and lazy evaluation. Designed for teaching, research and industrial applications, Haskell has pioneered a number of programming lan ...
.
Implementation 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:
def module MyModule do
@moduledoc """
Documentation for my module. With **formatting**.
"""
@doc "Hello"
def world do
"World"
end
end
Lisp
In Lisp, docstrings are known as documentation strings. The
Common Lisp
Common Lisp (CL) is a dialect of the Lisp programming language, published in ANSI standard document ''ANSI INCITS 226-1994 (S20018)'' (formerly ''X3.226-1994 (R1999)''). The Common Lisp HyperSpec, a hyperlinked HTML version, has been derived fro ...
standard states that a particular implementation may choose to discard docstrings whenever they want, for whatever reason. When they are kept, docstrings may be viewed and changed using the DOCUMENTATION function.
CLHS: Standard Generic Function DOCUMENTATION...
/ref> For instance:
(defun foo () "hi there" nil)
(documentation #'foo 'function) => "hi there"
Python
The common practice of documenting a code object at the head of its definition is captured by the addition of docstring syntax in the Python language.
The docstring for a Python code object (a module, class, or function) is the first statement of that code object, immediately following the definition (the 'def' or 'class' statement). The statement must be a bare string literal, not any other kind of expression. The docstring for the code object is available on that code object's __doc__
attribute and through the help
function.
The following Python file shows the declaration of docstrings within a Python source file:
"""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"""
Assuming that the above code was saved as , the following is an interactive session showing how the docstrings may be accessed:
>>> 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
>>>
Tools using docstrings
* cobra -doc (Cobra)
*doctest
doctest is a module included in the Python programming language's standard library that allows the easy generation of tests based on output from the standard Python interpreter shell, cut and pasted into docstrings.
Implementation specifics
Doc ...
(Python)
*Epydoc
Epydoc is a documentation generator that processes its own lightweight markup language Epytext for Python documentation strings. As opposed to freeform Python docstrings, reStructuredText (both also supported) and other markup languages for docst ...
(Python)
*Pydoc Pydoc is the standard documentation module for the programming language Python. Similar to the functionality of Perldoc within Perl and Javadoc within Java, Pydoc allows Python programmers to access Python's documentation help files, generate text ...
(Python)
*Sphinx
A sphinx ( , grc, σφίγξ , Boeotian: , plural sphinxes or sphinges) is a mythical creature with the head of a human, the body of a lion, and the wings of a falcon.
In Greek tradition, the sphinx has the head of a woman, the haunches of ...
(Python)
See also
*Literate programming
Literate programming is a programming paradigm introduced in 1984 by Donald Knuth in which a computer program is given as an explanation of its logic in a natural language, such as English, interspersed (embedded) with snippets of macros and t ...
– alternative code commenting paradigm
*Plain Old Documentation
Plain Old Documentation (pod) is a lightweight markup language used to document the Perl programming language as well as Perl modules and programs.
Design
Pod is designed to be a simple, clean language with just enough syntax to be useful. It pur ...
– Perl documentation
References
{{Reflist
External links
Python Docstrings
at Epydoc's SourceForge
SourceForge is a web service that offers software consumers a centralized online location to control and manage open-source software projects and research business software. It provides source code repository hosting, bug tracking, mirrorin ...
page
Documentation in GNU Emacs Lisp
from the doxygen
Doxygen ( ) is a documentation generator and static analysis tool for software source trees. When used as a documentation generator, Doxygen extracts information from specially-formatted comments within the code. When used for analysis, Doxyge ...
documentation about Python docstrings
Programming constructs
Lisp (programming language)
Python (programming language)
Software documentation
String (computer science)