In programming, a docstring is a string literal specified in source code that is used, like a comment, to document a specific segment of code. Unlike conventional source code comments, or even specifically formatted comments like Javadoc documentation, 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.
It appears to have been first introduced in the original TECO implementation of Emacs.[1]
Languages that support docstrings include Python, Lisp, Elixir, Clojure,[2] Gherkin,[3] Julia[4] and Haskell.[5]
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 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.[6] 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 mymodule.py, 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 (Python)
- Epydoc (Python)
- Pydoc (Python)
- Sphinx (Python)
See also
- Literate programming – alternative code commenting paradigm
- Plain Old Documentation – Perl documentation
References
- ^ "EMACS: The Extensible, Customizable Display Editor".
- ^ Function definition with docstring in Clojure
- ^ "Step Arguments - Doc Strings". Archived from the original on 2016-01-31. Retrieved 2016-06-22.
- ^ http://docs.julialang.org/en/stable/manual/documentation/
- ^ https://hackage.haskell.org/package/docstrings
- ^ CLHS: Standard Generic Function DOCUMENTATION...
External links
- Python Docstrings at Epydoc's Sourceforge page
- Documentation in GNU Emacs Lisp
- Section from the doxygen documentation about Python docstrings