Title: Theory / Unimportant / CS / Programming / Python / Lib / Docstring;
Tags: FromInstruction computer_to_instruction hasNotNewEffectReturnsMeaning some_instruction effetToQuestion

Name: A docstring
Definition: A string literal that occurs as the first statement in
a module, function, class, or method definition
Chapter: PEP 257 https://www.python.org/dev/peps/pep-0257/
Section: Specification

Name: Attribute docstring
Definition: String literals occurring immediately after a simple assignment at the top level of a module, class, or __init__ method
Chapter: PEP 257 https://www.python.org/dev/peps/pep-0257/
Section: Specification

Name: Additional docstring
Definition: String literals occurring immediately after another docstring
Chapter: PEP 257 https://www.python.org/dev/peps/pep-0257/
Section: Specification

Name: one-line docstring
Definition: A docstring which is a one-liner
Chapter: PEP 257 https://www.python.org/dev/peps/pep-0257/

Question: One-line docstring rule
Answer: The docstring is a phrase ending in a period. It prescribes the function or method's effect as a command ("Do this", "Return that"), not as a description; e.g. don't write "Returns the pathname ...".
Chapter: PEP 257 https://www.python.org/dev/peps/pep-0257/
Section: one-line docstring
Answer2: The one-line docstring should NOT be a "signature" reiterating the function method parameters (which can be obtained by introspection). Don't do:
def function(a, b):
"""function(a, b) -> list"""
Answer3: This type of docstring is only appropriate for C functions (such as built-ins), where introspection is not possible. However, the nature of the return value cannot be determined by introspection, so it should be mentioned. The preferred form for such a docstring would be something like:
def function(a, b):
"""Do X and return a list."""
(Of course "Do X" should be replaced by a useful description!)

Question: The docstring of a subclass
Answer: Should mention this and
summarize the differences. Use the verb "override" to indicate that a
subclass method replaces a superclass method and does not call the
superclass method; use the verb "extend" to indicate that a subclass
method calls the superclass method (in addition to its own behavior).
Chapter: Docstring https://www.python.org/dev/peps/pep-0257/
Section: Multi line docstring

Instruction: """foo"""
Effect: A docstring containing text foo
Language: Python
Chapter: PEP 257 https://www.python.org/dev/peps/pep-0257/
Section: Specification

Instruction: """foo
bar
"""
Effect: A multi-line doc string, with foo as a one-line docstring and bar as more elaborate instruction
Language: Python
Chapter: PEP 257 https://www.python.org/dev/peps/pep-0257/
Section: multi-line docstring

Instruction: The docstring of a script.
Effect: Its usage message
Language: Python
Chapter: Docstring https://www.python.org/dev/peps/pep-0257/
Section: Multi line docstring

Instruction: The docstring of a module
Effect: generally list the classes,
exceptions and functions (and any other 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 the object's
docstring.)
Language: Python
Chapter: Docstring https://www.python.org/dev/peps/pep-0257/
Section: Multi line docstring

Instruction: The docstring of a package
Effect: similare to docstring of module, and list modules and
subpackages exported by the package.
Language: Python
Chapter: Docstring https://www.python.org/dev/peps/pep-0257/
Section: Multi line docstring

Instruction: The docstring of a function/method
Effect: should summarize the behavior of the function/method and document its arguments, return value(s), side effects, exceptions raised, and restrictions on when it can be called (all if applicable).
Optional arguments should be indicated. It should be documented whether keyword arguments are part of the interface.
Language: Python
Chapter: Docstring https://www.python.org/dev/peps/pep-0257/
Section: Multi line docstring

Instruction: The docstring of a class
Effect: 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 class constructor should be documented in the docstring for its __init__ method. Individual methods should be documented by their own docstring.
Language: Python
Chapter: Docstring https://www.python.org/dev/peps/pep-0257/
Section: Multi line docstring

Instruction: keyword arguments:
var1 -- explanation1
...
varn -- explanationn
Effect: Adds explanation for the arguments of a function/method...
Language: Python
Chapter: https://www.python.org/dev/peps/pep-0257/
Section: Multi-line docstring
Where to use it: docstring