From ed08b5f70971e732515f458adf52a81be4fe6cd4 Mon Sep 17 00:00:00 2001 From: BethanyG Date: Fri, 8 May 2026 16:23:34 -0700 Subject: [PATCH 1/2] Updated stub docstrings to Google-style docstrings. --- .../concept/guidos-gorgeous-lasagna/lasagna.py | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/exercises/concept/guidos-gorgeous-lasagna/lasagna.py b/exercises/concept/guidos-gorgeous-lasagna/lasagna.py index 0e1a50d571e..d1d1ddf17f2 100644 --- a/exercises/concept/guidos-gorgeous-lasagna/lasagna.py +++ b/exercises/concept/guidos-gorgeous-lasagna/lasagna.py @@ -8,15 +8,18 @@ """ -#TODO: define your EXPECTED_BAKE_TIME (required) and PREPARATION_TIME (optional) constants below. +#TODO (student): define your EXPECTED_BAKE_TIME (required) and PREPARATION_TIME (optional) constants below. -#TODO: Remove 'pass' and complete the 'bake_time_remaining()' function below. +#TODO (student): Remove 'pass' and complete the 'bake_time_remaining()' function below. def bake_time_remaining(): """Calculate the bake time remaining. - :param elapsed_bake_time: int - baking time already elapsed. - :return: int - remaining bake time (in minutes) derived from 'EXPECTED_BAKE_TIME'. + Parameters:\ + elapsed_bake_time (int): The baking time already elapsed. + + Returns: + int: The remaining bake time (in minutes) derived from 'EXPECTED_BAKE_TIME'. Function that takes the actual minutes the lasagna has been in the oven as an argument and returns how many minutes the lasagna still needs to bake @@ -26,16 +29,16 @@ def bake_time_remaining(): pass -#TODO: Define the 'preparation_time_in_minutes()' function below. +#TODO (student): Define the 'preparation_time_in_minutes()' function below. # To avoid the use of magic numbers (see: https://en.wikipedia.org/wiki/Magic_number_(programming)), you should define a PREPARATION_TIME constant. # You can do that on the line below the 'EXPECTED_BAKE_TIME' constant. # This will make it easier to do calculations, and make changes to your code. -#TODO: define the 'elapsed_time_in_minutes()' function below. +#TODO (student): define the 'elapsed_time_in_minutes()' function below. -# TODO: Remember to go back and add docstrings to all your functions +# TODO (student): Remember to go back and add docstrings to all your functions # (you can copy and then alter the one from bake_time_remaining.) From c476907b027edbef0c6801b641f751381a4828fe Mon Sep 17 00:00:00 2001 From: BethanyG Date: Sat, 9 May 2026 11:51:48 -0700 Subject: [PATCH 2/2] Updated docstring explainations and refs to use Google style. --- .../guidos-gorgeous-lasagna/.docs/hints.md | 2 + .../.docs/instructions.md | 12 +++-- .../.docs/introduction.md | 51 ++++++++++++------- .../guidos-gorgeous-lasagna/lasagna.py | 2 +- 4 files changed, 44 insertions(+), 23 deletions(-) diff --git a/exercises/concept/guidos-gorgeous-lasagna/.docs/hints.md b/exercises/concept/guidos-gorgeous-lasagna/.docs/hints.md index 96668ffbd0b..fca46fc65fd 100644 --- a/exercises/concept/guidos-gorgeous-lasagna/.docs/hints.md +++ b/exercises/concept/guidos-gorgeous-lasagna/.docs/hints.md @@ -38,6 +38,7 @@ ## 5. Update the recipe with notes - Clearly [commenting][comments] and [documenting][docstrings] your code according to [PEP257][pep257] is always recommended. +- Some examples of Google-style docstrings can be found in the Sphinx documentation for the [napoleon module][napoleon]. [assignment]: https://docs.python.org/3/reference/simple_stmts.html#grammar-token-assignment-stmt [comments]: https://realpython.com/python-comments-guide/ @@ -46,6 +47,7 @@ [docstrings]: https://docs.python.org/3/tutorial/controlflow.html#tut-docstrings [magic-numbers]: https://en.wikipedia.org/wiki/Magic_number_(programming) [naming]: https://realpython.com/python-variables/ +[napoleon]: https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html#module-sphinx.ext.napoleon [numbers]: https://docs.python.org/3/tutorial/introduction.html#numbers [pep257]: https://www.python.org/dev/peps/pep-0257/ [python as a calculator]: https://docs.python.org/3/tutorial/introduction.html#using-python-as-a-calculator diff --git a/exercises/concept/guidos-gorgeous-lasagna/.docs/instructions.md b/exercises/concept/guidos-gorgeous-lasagna/.docs/instructions.md index c566db91120..f3acc137c11 100644 --- a/exercises/concept/guidos-gorgeous-lasagna/.docs/instructions.md +++ b/exercises/concept/guidos-gorgeous-lasagna/.docs/instructions.md @@ -78,14 +78,18 @@ Go back through the recipe, adding "notes" in the form of [function docstrings][ ```python def elapsed_time_in_minutes(number_of_layers, elapsed_bake_time): """Calculate the elapsed cooking time. - - :param number_of_layers: int - the number of layers in the lasagna. - :param elapsed_bake_time: int - time the lasagna has been baking in the oven. - :return: int - total time elapsed (in minutes) preparing and baking. + + Parameters: + number_of_layers (int): The number of layers in the lasagna. + elapsed_bake_time (int): Time the lasagna has been baking in the oven. + + Returns: + int: The total time elapsed (in minutes) preparing and baking. This function takes two integers representing the number of lasagna layers and the time already spent baking the lasagna. It calculates the total elapsed minutes spent cooking (preparing + baking). + """ ``` diff --git a/exercises/concept/guidos-gorgeous-lasagna/.docs/introduction.md b/exercises/concept/guidos-gorgeous-lasagna/.docs/introduction.md index eb755bcfe23..166063057d6 100644 --- a/exercises/concept/guidos-gorgeous-lasagna/.docs/introduction.md +++ b/exercises/concept/guidos-gorgeous-lasagna/.docs/introduction.md @@ -209,13 +209,18 @@ Docstrings are declared using triple double quotes (""") indented at the same le ```python -# An example from PEP257 of a multi-line docstring. +# An example from PEP257 of a multi-line docstring +# reformatted to use Google style non-type hinted docstrings. +# Some additional details can be found in the Sphinx documentation: +# https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html#getting-started + def complex(real=0.0, imag=0.0): """Form a complex number. - Keyword arguments: - real -- the real part (default 0.0) - imag -- the imaginary part (default 0.0) + Keyword Arguments: + real (float): The real part of the number (default 0.0) + imag (float): The imaginary part of the number (default 0.0) + """ if imag == 0.0 and real == 0.0: @@ -224,36 +229,45 @@ def complex(real=0.0, imag=0.0): ``` -Docstrings are read by automated documentation tools and are returned by calling the special attribute `.__doc__` on the function, method, or class name. -Docstring conventions are laid out in [PEP257][pep257]. +Docstrings are read by automated documentation tools such as [Sphinx][sphinx] and are returned by calling the special attribute `.__doc__` on the function, method, or class name. +General docstring conventions are laid out in [PEP257][pep257], but exact formats will vary by project and team. +Exercism concept exercises try to follow the Google style for un-type hinted code. Docstrings can also function as [lightweight unit tests][doctests], which will be covered in a later exercise. ```python # An example on a user-defined function. +# This uses Google style docstrings. >>> def raise_to_power(number, power): - """Raise a number to an arbitrary power. - - :param number: int the base number. - :param power: int the power to raise the base number to. - :return: int - number raised to the specified power. + """Raise a number to an arbitrary power. + + Parameters: + number (int): The base number. + power (int): The power to raise the base number to. + + Returns: + int: The number raised to the specified power. + + Takes a number and raises it to the specified power, returning the result. - Takes a number and raises it to the specified power, returning the result. - """ + """ - return number ** power + return number ** power ... # Calling the .__doc__ attribute of the function and printing the result. >>> print(raise_to_power.__doc__) Raise a number to an arbitrary power. - :param number: int the base number. - :param power: int the power to raise the base number to. - :return: int - number raised to the specified power. +Parameters: + number (int): The base number. + power (int): The power to raise the base number to. - Takes a number and raises it to the specified power, returning the result. +Returns: + int: The number raised to the specified power. + +Takes a number and raises it to the specified power, returning the result. ``` [calls]: https://docs.python.org/3/reference/expressions.html#calls @@ -271,4 +285,5 @@ Raise a number to an arbitrary power. [parameters]: https://docs.python.org/3/glossary.html#term-parameter [pep257]: https://www.python.org/dev/peps/pep-0257/ [return]: https://docs.python.org/3/reference/simple_stmts.html#return +[sphinx]: https://www.sphinx-doc.org/en/master/usage/index.html [type hints]: https://docs.python.org/3/library/typing.html diff --git a/exercises/concept/guidos-gorgeous-lasagna/lasagna.py b/exercises/concept/guidos-gorgeous-lasagna/lasagna.py index d1d1ddf17f2..bdf8ca9b778 100644 --- a/exercises/concept/guidos-gorgeous-lasagna/lasagna.py +++ b/exercises/concept/guidos-gorgeous-lasagna/lasagna.py @@ -15,7 +15,7 @@ def bake_time_remaining(): """Calculate the bake time remaining. - Parameters:\ + Parameters: elapsed_bake_time (int): The baking time already elapsed. Returns: