Docstring
Jump to navigation
Jump to search
A Docstring is a string literal specified in source code that is used to document a specific segment of code.
- Context:
- It can (typically) include a description of the function/module/class/script, its parameters, return values, and any exceptions raised.
- It can (often) be accessed programmatically at runtime, enabling dynamic generation of documentation or usage guides.
- It can be used to document Functions, Classes, Modules, or even entire Scripts.
- It can serve as an integral part of Automatic Documentation Generation tools.
- It can vary in syntax and usage across different Programming Languages that support docstrings.
- It can follow specific conventions within a programming language to enhance readability and utility.
- It can be enclosed in triple quotes in languages like Python to denote multiline string literals for comprehensive documentation.
- It can be used in some languages like Python and Haskell as a form of Test-Driven Development, where tests are included within the docstring.
- It can be part of the language's official style guide, as in PEP 257 for Python.
- ...
- Example(s):
- Use the Triple Quote Approach for multiline docstrings, such as:
- A Python Docstring, like:
python def my_function(): """This is a docstring describing the function.""" pass. - A Julia Docstring, like:
julia """ This is a docstring describing the function. """ function myFunction() end. - ...
- A Python Docstring, like:
- Use the Comment-Based Approach for single or multiline docstrings in languages without triple quotes, such as:
- A Haskell Docstring, like:
haskell {-| This is a docstring describing the function. -} myFunction = .... - ...
- A Haskell Docstring, like:
- ...
- Use the Triple Quote Approach for multiline docstrings, such as:
- Counter-Example(s):
- See: Comment (Computer Programming), Docblock, Automatic Documentation Generation, PEP 257.
References
2024
- (Wikipedia, 2024) ⇒ https://en.wikipedia.org/wiki/Docstring Retrieved:2024-3-10.
- 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 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.
Languages that support docstrings include Python, Lisp, Elixir, Clojure, Gherkin, Julia and Haskell.
- 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 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.