diff options
| -rw-r--r-- | bot/resources/tags/docstring.md | 28 |
1 files changed, 14 insertions, 14 deletions
diff --git a/bot/resources/tags/docstring.md b/bot/resources/tags/docstring.md index 9457b629c..20043131e 100644 --- a/bot/resources/tags/docstring.md +++ b/bot/resources/tags/docstring.md @@ -1,18 +1,18 @@ -A [`docstring`](https://docs.python.org/3/glossary.html#term-docstring) is a string with triple quotes that often used in file, classes, functions, etc. A docstring should have a clear explanation of exactly what the function does. You can also include descriptions of the function's parameter(s) and its return type, as shown below. +A [`docstring`](https://docs.python.org/3/glossary.html#term-docstring) is a string - always using triple quotes - that's placed at the top of files, classes and functions. A docstring should contain a clear explanation of what it's describing. You can also include descriptions of the subject's parameter(s) and what it returns, as shown below: ```py -def greet(name, age) -> str: - """ - Return a string that greets the given person, including their name and age. +def greet(name: str, age: int) -> str: + """ + Return a string that greets the given person, using their name and age. - :param name: The name to greet. - :type name: str - :param age: The age to display. - :type age: int - :return: String of the greeting. - """ - return_string = f"Hello, {name} you are {age} years old!" - return return_string + :param name: The name of the person to greet. + :param age: The age of the person to greet. + + :return: The greeting. + """ + return f"Hello {name}, you are {age} years old!" ``` -You can get the docstring by using `.__doc__` attribute. For the last example you can get it through: `print(greet.__doc__)`. +You can get the docstring by using the [`inspect.getdoc`](https://docs.python.org/3/library/inspect.html#inspect.getdoc) function, from the built-in [`inspect`](https://docs.python.org/3/library/inspect.html) module, or by accessing the `.__doc__` attribute. `inspect.getdoc` is often preferred, as it clears indents from the docstring. + +For the last example, you can print it by doing this: `print(inspect.getdoc(greet))`. -For more details about what docstring is and it's usage check out this guide by [Real Python](https://realpython.com/documenting-python-code/#docstrings-background), or the [PEP-257 docs](https://www.python.org/dev/peps/pep-0257/#what-is-a-docstring). +For more details about what a docstring is and its usage, check out this guide by [Real Python](https://realpython.com/documenting-python-code/#docstrings-background), or the [official docstring specification](https://www.python.org/dev/peps/pep-0257/#what-is-a-docstring). |