From a2592d0b205e43c676106258a059df13a99fd191 Mon Sep 17 00:00:00 2001 From: Chris Lovering Date: Fri, 23 Jul 2021 10:40:52 +0100 Subject: update docstring command to use 4 space indents. --- bot/resources/tags/docstring.md | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/bot/resources/tags/docstring.md b/bot/resources/tags/docstring.md index 9457b629c..33452b998 100644 --- a/bot/resources/tags/docstring.md +++ b/bot/resources/tags/docstring.md @@ -1,17 +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. ```py def greet(name, age) -> str: - """ - Return a string that greets the given person, including their name and age. + """ + Return a string that greets the given person, including 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 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 ``` You can get the docstring by using `.__doc__` attribute. For the last example you can get it through: `print(greet.__doc__)`. -- cgit v1.2.3 From 1abbb06bcb330be672ef4c979f5d83d8b3bbafad Mon Sep 17 00:00:00 2001 From: Chris Lovering Date: Fri, 23 Jul 2021 10:41:30 +0100 Subject: Fix grammar issues in docstring tag --- bot/resources/tags/docstring.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/bot/resources/tags/docstring.md b/bot/resources/tags/docstring.md index 33452b998..2918281c3 100644 --- a/bot/resources/tags/docstring.md +++ b/bot/resources/tags/docstring.md @@ -1,4 +1,4 @@ -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 with 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 its return type, as shown below: ```py def greet(name, age) -> str: """ @@ -9,11 +9,10 @@ def greet(name, age) -> str: :param age: The age to display. :type age: int - :return: String of the greeting. + :return: String representation of the greeting. """ - return_string = f"Hello, {name} you are {age} years old!" - return return_string + 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 `.__doc__` attribute. For the last example, you can print it by doing this: `print(greet.__doc__)`. -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 [PEP-257 docs](https://www.python.org/dev/peps/pep-0257/#what-is-a-docstring). -- cgit v1.2.3 From 1dec12a1b024283cc3464f0f81bb78375280e82c Mon Sep 17 00:00:00 2001 From: Chris Lovering Date: Fri, 23 Jul 2021 11:02:57 +0100 Subject: Move type docs to type hints --- bot/resources/tags/docstring.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/bot/resources/tags/docstring.md b/bot/resources/tags/docstring.md index 2918281c3..7144d3702 100644 --- a/bot/resources/tags/docstring.md +++ b/bot/resources/tags/docstring.md @@ -1,13 +1,11 @@ A [`docstring`](https://docs.python.org/3/glossary.html#term-docstring) is a string with 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 its return type, as shown below: ```py -def greet(name, age) -> str: +def greet(name: str, age: int) -> str: """ Return a string that greets the given person, including their name and age. :param name: The name to greet. - :type name: str :param age: The age to display. - :type age: int :return: String representation of the greeting. """ -- cgit v1.2.3 From fb7ec43edc0581175cb86fed7df48ef7efb6e743 Mon Sep 17 00:00:00 2001 From: ChrisJL Date: Fri, 23 Jul 2021 11:17:43 +0100 Subject: Refer to PEP-257 as the official spec This is for users who may not know what a PEP is. Co-authored-by: Bluenix --- bot/resources/tags/docstring.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/bot/resources/tags/docstring.md b/bot/resources/tags/docstring.md index 7144d3702..8d6fd3615 100644 --- a/bot/resources/tags/docstring.md +++ b/bot/resources/tags/docstring.md @@ -13,4 +13,4 @@ def greet(name: str, age: int) -> str: ``` You can get the docstring by using the `.__doc__` attribute. For the last example, you can print it by doing this: `print(greet.__doc__)`. -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 [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). -- cgit v1.2.3 From 4b1cf360f0f7b3bcc400184a127ce74b8c98148b Mon Sep 17 00:00:00 2001 From: Chris Lovering Date: Fri, 23 Jul 2021 11:19:30 +0100 Subject: Further describe the funciton in docstring tag --- bot/resources/tags/docstring.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/bot/resources/tags/docstring.md b/bot/resources/tags/docstring.md index 8d6fd3615..95ad13b35 100644 --- a/bot/resources/tags/docstring.md +++ b/bot/resources/tags/docstring.md @@ -1,11 +1,11 @@ -A [`docstring`](https://docs.python.org/3/glossary.html#term-docstring) is a string with 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 its return type, as shown below: +A [`docstring`](https://docs.python.org/3/glossary.html#term-docstring) is a string with 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: str, age: int) -> str: """ - Return a string that greets the given person, including their name and age. + Return a string that greets the given person, using their name and age. - :param name: The name to greet. - :param age: The age to display. + :param name: The name of the person to greet. + :param age: The age of the person to greet. :return: String representation of the greeting. """ -- cgit v1.2.3 From e5ebccc410c38ba84eca555ecef72c4a91cf8779 Mon Sep 17 00:00:00 2001 From: Chris Lovering Date: Fri, 23 Jul 2021 11:28:58 +0100 Subject: Update grammer in docstring tag Co-authored-by: Bluenix --- bot/resources/tags/docstring.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/bot/resources/tags/docstring.md b/bot/resources/tags/docstring.md index 95ad13b35..0160d5ff3 100644 --- a/bot/resources/tags/docstring.md +++ b/bot/resources/tags/docstring.md @@ -1,4 +1,4 @@ -A [`docstring`](https://docs.python.org/3/glossary.html#term-docstring) is a string with 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: +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: str, age: int) -> str: """ @@ -7,7 +7,7 @@ def greet(name: str, age: int) -> str: :param name: The name of the person to greet. :param age: The age of the person to greet. - :return: String representation of the greeting. + :return: The greeting. """ return f"Hello {name}, you are {age} years old!" ``` -- cgit v1.2.3 From 39500b40ac2892cb469366103022bd854f7734b2 Mon Sep 17 00:00:00 2001 From: Chris Lovering Date: Fri, 23 Jul 2021 12:14:28 +0100 Subject: Suggest inspect.getdoc in docstring tag Co-authored-by: Numerlor <25886452+Numerlor@users.noreply.github.com> --- bot/resources/tags/docstring.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/bot/resources/tags/docstring.md b/bot/resources/tags/docstring.md index 0160d5ff3..20043131e 100644 --- a/bot/resources/tags/docstring.md +++ b/bot/resources/tags/docstring.md @@ -11,6 +11,8 @@ def greet(name: str, age: int) -> str: """ return f"Hello {name}, you are {age} years old!" ``` -You can get the docstring by using the `.__doc__` attribute. For the last example, you can print it by doing this: `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 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). -- cgit v1.2.3