Fix minor inconsistencies in introduction.md of guidos-gorgeous-lasagna (#4073)

* Fix minor inconsistencies in introduction.md

- Update output to be consistent with the Python interactive-interpreter (e.g. print() prints its argument string without quotes).
- Replace "Python terminal" with "Python shell" for accuracy. While informally acceptable, they are technically different (a shell runs inside a terminal).
- Change parenthesis to plural form: parentheses
- Replace "return expression" with "return statement" for accuracy.

* Refine basic concepts after forum discussions

* Clarify comment on the call to str.upper()

Author: helanabi

concepts/basics/about.md

@@ -68,16 +68,17 @@ For example, `my_first_variable` can be re-assigned many times using `=`, and ca
 >>> print(type(my_first_variable))
 <class 'str'>
 
+>>> my_first_variable = 'You can call me "str".' # Strings can be declared using single or double quote marks.
 >>> print(my_first_variable)
-"Now, I'm a string."  # Strings can be declared using single or double quote marks.
+You can call me "str".
 
 import collections
 >>> my_first_variable = collections.Counter([1,1,2,3,3,3,4,5,6,7]) # Now my_first_variable has been re-bound to a Counter object.
 >>> print(type(my_first_variable))
 <class 'collections.Counter'>
 
 >>> print(my_first_variable)
->>> Counter({3: 3, 1: 2, 2: 1, 4: 1, 5: 1, 6: 1, 7: 1})
+Counter({3: 3, 1: 2, 2: 1, 4: 1, 5: 1, 6: 1, 7: 1})
 ```
 
 
@@ -108,7 +109,7 @@ When functions are bound to a [class][classes] name, they're referred to as [met
 Related functions and classes (_with their methods_) can be grouped together in the same file or module, and imported in part or in whole for use in other programs.
 
 The `def` keyword begins a [function definition][function definition].
-Each function can have zero or more formal [parameters][parameters] in `()` parenthesis, followed by a `:` colon.
+Each function can have zero or more formal [parameters][parameters] in `()` parentheses, followed by a `:` colon.
 Statements for the _body_ of the function begin on the line following `def` and must be _indented in a block_:
 
 
@@ -144,7 +145,7 @@ def add_two_numbers(number_one, number_two):
   return number_one + number_two   
 
 
-# Calling the function in the Python terminal returns the sum of the numbers.
+# Calling the function in the Python shell returns the sum of the numbers.
 >>> add_two_numbers(3, 4)
 7
 
@@ -155,28 +156,42 @@ def add_two_numbers(number_one, number_two):
 11
 ```
 
-Functions that do not have an _explicit_ `return` expression will _implicitly_ return the [`None`][none] object.
+Functions that do not have an _explicit_ expression following a `return` will _implicitly_ return the [`None`][none] object.
 The details of `None` will be covered in a later exercise.
 For the purposes of this exercise and explanation, `None` is a placeholder that represents nothing, or null:
 
 
 ```python
-# This function does not have an explicit return.
-def add_two_numbers(number_one, number_two):
-  result = number_one + number_two
 
+# This function will return `None`
+def square_a_number(number):
+    square = number * number
+    return # <-- note that this return is not followed by an expression
 
-# Calling the function in the Python terminal appears 
+# Calling the function in the Python shell appears 
 # to not return anything at all.
->>> add_two_numbers(5, 7)
+>>> square_a_number(2)
 >>>
 
 
 # Using print() with the function call shows that 
 # the function is actually returning the **None** object.
->>> print(add_two_numbers(5, 7))
+>>> print(square_a_number(2))
 None
+```
+
+Functions that omit `return` will also  _implicitly_ return the [`None`][none] object.
+This means that if you do not use `return` in a function, Python will return the `None` object for you.
+
+```python
+
+# This function omits a return keyword altogether
+def add_two_numbers(number_one, number_two):
+  result = number_one + number_two
 
+>>> add_two_numbers(5, 7)
+>>> print(add_two_numbers(5, 7))
+None
 
 # Assigning the function call to a variable and printing 
 # the variable will also show None.
@@ -192,32 +207,32 @@ Functions are [_called_][calls] or invoked using their name followed by `()`.
 Dot (`.`) notation is used for calling functions defined inside a class or module.
 
 ```python
->>> def number_to_the_power_of(number_one, number_two):
-        return number_one ** number_two
+>>> def raise_to_power(number, power):
+        return number ** power
 ...
 
->>> number_to_the_power_of(3,3) # Invoking the function with the arguments 3 and 3.
+>>> raise_to_power(3,3) # Invoking the function with the arguments 3 and 3.
 27
 
 
 # A mis-match between the number of parameters and the number of arguments will raise an error.
->>> number_to_the_power_of(4,)
+>>> raise_to_power(4,)
 ...
 Traceback (most recent call last):
   File "<stdin>", line 1, in <module>
-TypeError: number_to_the_power_of() missing 1 required positional argument: 'number_two'
+TypeError: raise_to_power() missing 1 required positional argument: 'power'
 
 
 # Calling methods or functions in classes and modules.
 >>> start_text = "my silly sentence for examples."
->>> str.upper(start_text)  # Calling the upper() method for the built-in str class.
-"MY SILLY SENTENCE FOR EXAMPLES."
+>>> str.upper(start_text)  # Calling the upper() method from the built-in str class on start_text.
+'MY SILLY SENTENCE FOR EXAMPLES.'
 
 # Importing the math module
 import math
 
 >>> math.pow(2,4)  # Calling the pow() function from the math module
->>> 16.0
+16.0
 ```
 
 
@@ -273,32 +288,32 @@ Testing and `doctest` will be covered in a later concept.
 
 ```python
 # An example on a user-defined function.
->>> def number_to_the_power_of(number_one, number_two):
+>>> def raise_to_power(number, power):
         """Raise a number to an arbitrary power.
 
-        :param number_one: int the base number.
-        :param number_two: int the power to raise the base number to.
-        :return: int - number raised to power of second number
+        :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.
 
-        Takes number_one and raises it to the power of number_two, returning the result.
+        Takes a number and raises it to the specified power, returning the result.
         """
 
-        return number_one ** number_two
+        return number ** power
 ...
 
 # Calling the .__doc__ attribute of the function and printing the result.
->>> print(number_to_the_power_of.__doc__)
+>>> print(raise_to_power.__doc__)
 Raise a number to an arbitrary power.
 
-    :param number_one: int the base number.
-    :param number_two: int the power to raise the base number to.
-    :return: int - number raised to power of second number
+    :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.
 
-    Takes number_one and raises it to the power of number_two, returning the result.
+    Takes a number and raises it to the specified power, returning the result.
 
 
 
-# Printing the __doc__ attribute for the built-in type: str.
+# Printing the __doc__ attribute of the built-in type: str.
 >>> print(str.__doc__)
 str(object='') -> str
 str(bytes_or_buffer[, encoding[, errors]]) -> str

concepts/basics/introduction.md

@@ -38,8 +38,9 @@ A name can be reassigned (or re-bound) to different values (different object typ
 >>> print(type(my_first_variable))
 <class 'str'>
 
+>>> my_first_variable = 'You can call me "str".' #<-- Strings can be declared using single or double quote marks.
 >>> print(my_first_variable)
-"Now, I'm a string."  # Strings can be declared using single or double quote marks.
+You can call me "str".
 ```
 
 
@@ -54,7 +55,7 @@ Constants should be defined at a [module][module] (file) level, and are typicall
 ## Functions
 
 The `def` keyword begins a [function definition][function definition].
-Each function can have zero or more formal [parameters][parameters] in `()` parenthesis, followed by a `:` colon.
+Each function can have zero or more formal [parameters][parameters] in `()` parentheses, followed by a `:` colon.
 Statements for the _body_ of the function begin on the line following `def` and must be _indented in a block_.
 
 
@@ -90,7 +91,7 @@ def add_two_numbers(number_one, number_two):
   return number_one + number_two   
 
 
-# Calling the function in the Python terminal returns the sum of the numbers.
+# Calling the function in the Python shell returns the sum of the numbers.
 >>> add_two_numbers(3, 4)
 7
 
@@ -102,29 +103,42 @@ def add_two_numbers(number_one, number_two):
 ```
 
 
-Functions that do not have an _explicit_ `return` expression will _implicitly_ return the [`None`][none] object.
-This means that if you do not use `return` in a function, Python will return the `None` object for you.
+Functions that do not have an _explicit_ expression following a `return` will _implicitly_ return the [`None`][none] object.
 The details of `None` will be covered in a later exercise.
 For the purposes of this exercise and explanation, `None` is a placeholder that represents nothing, or null:
 
 
 ```python
-# This function does not have an explicit return.
-def add_two_numbers(number_one, number_two):
-  result = number_one + number_two
 
+# This function will return `None`
+def square_a_number(number):
+    square = number * number
+    return # <-- note that this return is not followed by an expression
 
-# Calling the function in the Python terminal appears 
+# Calling the function in the Python shell appears 
 # to not return anything at all.
->>> add_two_numbers(5, 7)
+>>> square_a_number(2)
 >>>
 
 
 # Using print() with the function call shows that 
 # the function is actually returning the **None** object.
->>> print(add_two_numbers(5, 7))
+>>> print(square_a_number(2))
 None
+```
+
+Functions that omit `return` will also  _implicitly_ return the [`None`][none] object.
+This means that if you do not use `return` in a function, Python will return the `None` object for you.
 
+```python
+
+# This function omits a return keyword altogether
+def add_two_numbers(number_one, number_two):
+  result = number_one + number_two
+
+>>> add_two_numbers(5, 7)
+>>> print(add_two_numbers(5, 7))
+None
 
 # Assigning the function call to a variable and printing 
 # the variable will also show None.