From d6c237cc6d2b1efa21d917df1afa5b5c425c0cc6 Mon Sep 17 00:00:00 2001 From: NotFlameDev <78838310+NotFlameDev@users.noreply.github.com> Date: Wed, 21 Jul 2021 10:14:02 +0700 Subject: Added docstring tag --- bot/resources/tags/docstring.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) create mode 100644 bot/resources/tags/docstring.md diff --git a/bot/resources/tags/docstring.md b/bot/resources/tags/docstring.md new file mode 100644 index 000000000..88f6b3a1d --- /dev/null +++ b/bot/resources/tags/docstring.md @@ -0,0 +1,16 @@ +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. Docstrings usually has clear explanation, parameter(s) and return type. + +Here's an example of usage of a docstring: +```py +def greet(name, age) -> str: + """ + :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 d462ad0541acbd0f3282190a0648c28232563767 Mon Sep 17 00:00:00 2001 From: NotFlameDev <78838310+NotFlameDev@users.noreply.github.com> Date: Thu, 22 Jul 2021 08:01:35 +0700 Subject: Changed the documentation as intended --- bot/resources/tags/docstring.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/bot/resources/tags/docstring.md b/bot/resources/tags/docstring.md index 88f6b3a1d..cf5413f4b 100644 --- a/bot/resources/tags/docstring.md +++ b/bot/resources/tags/docstring.md @@ -1,9 +1,11 @@ -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. Docstrings usually has clear explanation, parameter(s) and return type. +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 usually has clear explanation (such as what the function do, purposes of the function, and other details of the function), parameter(s) and a return type. -Here's an example of usage of a docstring: +Here's an example of a docstring: ```py def greet(name, age) -> str: """ + Greet someone with their name and age. + :param name: The name to greet. :type name: str :param age: The age to display. @@ -14,3 +16,5 @@ def greet(name, age) -> str: return return_string ``` You can get the docstring by using `.__doc__` attribute. For the last example you can get it through: `print(greet.__doc__)`. + +For more details about what docstring is and it's usage check out [https://realpython.com/documenting-python-code/#docstrings-background](realpython) or [https://www.python.org/dev/peps/pep-0257/#what-is-a-docstring](official PEP docs). -- cgit v1.2.3 From 4fff8ff555162c3a8c99fbbb2f6c62a6366704d9 Mon Sep 17 00:00:00 2001 From: NotFlameDev <78838310+NotFlameDev@users.noreply.github.com> Date: Fri, 23 Jul 2021 08:06:06 +0700 Subject: Hyperlink fix Co-authored-by: ChrisJL --- 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 cf5413f4b..31d9b239a 100644 --- a/bot/resources/tags/docstring.md +++ b/bot/resources/tags/docstring.md @@ -17,4 +17,4 @@ def greet(name, age) -> str: ``` You can get the docstring by using `.__doc__` attribute. For the last example you can get it through: `print(greet.__doc__)`. -For more details about what docstring is and it's usage check out [https://realpython.com/documenting-python-code/#docstrings-background](realpython) or [https://www.python.org/dev/peps/pep-0257/#what-is-a-docstring](official PEP docs). +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). -- cgit v1.2.3 From ed142e5251000fe12a39844feec31a308e391d96 Mon Sep 17 00:00:00 2001 From: NotFlameDev <78838310+NotFlameDev@users.noreply.github.com> Date: Fri, 23 Jul 2021 08:06:26 +0700 Subject: Update docstring explanation. Co-authored-by: ChrisJL --- 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 31d9b239a..feafecc41 100644 --- a/bot/resources/tags/docstring.md +++ b/bot/resources/tags/docstring.md @@ -4,7 +4,7 @@ Here's an example of a docstring: ```py def greet(name, age) -> str: """ - Greet someone with 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 -- cgit v1.2.3 From b6d339e46b2fb445d00a8c78e796ee97296baaa2 Mon Sep 17 00:00:00 2001 From: NotFlameDev <78838310+NotFlameDev@users.noreply.github.com> Date: Fri, 23 Jul 2021 08:13:19 +0700 Subject: Update docstring's explanation --- 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 feafecc41..9457b629c 100644 --- a/bot/resources/tags/docstring.md +++ b/bot/resources/tags/docstring.md @@ -1,6 +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 usually has clear explanation (such as what the function do, purposes of the function, and other details of the function), parameter(s) and a return type. - -Here's an example of a docstring: +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: """ -- cgit v1.2.3