Docstring

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, but 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] and Julia.[4]

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:

defmodule 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. 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(object):
    """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
>>>

Content of Python docstrings

The docstring of a script (a stand-alone program) should be usable as its "usage" message, printed when the script is invoked with incorrect or missing arguments (or perhaps with a "-h" option, for "help"). Such a docstring should document the script's purpose, command line parameters and any dependencies. Usage messages can be fairly elaborate (several screens full) and should be sufficient for a new user to use the script properly, as well as provide a complete quick reference to all options and arguments for the sophisticated user.
If the stand-alone script uses another module for handling options, such as the argparse module, then option information is moved from the docstring to the module's utilities.

The docstring for a module should generally list all classes, exceptions, functions and objects that are exported by the module, with a one-line summary of each. (These summaries generally give less detail than the summary line in each object's docstring.)

The docstring for a package (i.e., the docstring of the package's __init__.py module) should also list the modules and subpackages exported by the package.

The docstring for a class should summarize its behavior and list the public methods and instance variables. If the class is intended to be subclassed, and has an additional interface for subclasses, this interface should be listed separately in the docstring.

The docstring for a function or a method should generally be an imperative sentence ending in a period, prescribing its behavior (e.g. "Do this ..."), rather than a description (e.g. "The function does this ..."). When the function is not trivial, it should be a multiline-string, with the imperative sentence being followed by a more in-depth summary of the function's behavior and a documentation of its arguments (including default values and other relevant details), return value(s), side effects, exceptions raised, and any restrictions on when it can be called (all if applicable).

There are conventions for the placement of quotation marks and newlines.[5]

Tools using docstrings

See also

References

  1. ↑ "EMACS: The Extensible, Customizable Display Editor".
  2. ↑ Function definition with docstring in Clojure
  3. ↑ Step Arguments - Doc Strings
  4. ↑ http://docs.julialang.org/en/stable/manual/documentation/
  5. ↑ one-linemulti-line
This article is issued from Wikipedia. The text is licensed under Creative Commons - Attribution - Sharealike. Additional terms may apply for the media files.