docstring tutorial for zaab1t

README.md

@@ -50,6 +50,7 @@ to learn more about whatever you want after studying it.
 18. [Modules](basics/modules.md)
 19. [Exceptions](basics/exceptions.md)
 20. [Classes](basics/classes.md)
+21. [Docstrings](basics/docstrings.md)
 
 ### Advanced
 

advanced/datatypes.md

@@ -398,5 +398,5 @@ star](../README.md#how-can-i-thank-you-for-writing-and-sharing-this-tutorial).
 You may use this tutorial freely at your own risk. See
 [LICENSE](../LICENSE).
 
-[Previous](../basics/classes.md) | [Next](functions.md) |
+[Previous](../basics/docstrings.md) | [Next](functions.md) |
 [List of contents](../README.md#advanced)

basics/README.md

@@ -26,6 +26,7 @@ to learn more about whatever you want after studying it.
 18. [Modules](modules.md)
 19. [Exceptions](exceptions.md)
 20. [Classes](classes.md)
+21. [Docstrings](docstrings.md)
 
 ***
 

basics/classes.md

@@ -424,5 +424,5 @@ star](../README.md#how-can-i-thank-you-for-writing-and-sharing-this-tutorial).
 You may use this tutorial freely at your own risk. See
 [LICENSE](../LICENSE).
 
-[Previous](exceptions.md) | [Next](../advanced/datatypes.md) |
+[Previous](exceptions.md) | [Next](docstrings.md) |
 [List of contents](../README.md#basics)

basics/docstrings.md

@@ -0,0 +1,228 @@
+# Help and Docstrings
+
+In this tutorial we have used `help()` a few times. It's great and you
+can use it as much as you want to. For example, running `help(str)`
+displays a nice list of all string methods and explanations of what they
+do, and `help(list.extend)` explains what extending something to a list
+does.
+
+You can get help of many other things too. For example:
+
+```python
+>>> stuff = []
+>>> help(stuff.append)
+Help on built-in function append:
+
+append(object, /) method of builtins.list instance
+    Append object to the end of the list.
+
+>>> help(print)
+Help on built-in function print in module builtins:
+
+print(...)
+    print(value, ..., sep=' ', end='\n', file=sys.stdout, flush=False)
+
+    Prints the values to a stream, or to sys.stdout by default.
+    Optional keyword arguments:
+    ...
+```
+
+## Docstrings
+
+Let's see what happens if we [define a function](defining-functions.md)
+and call `help()` on that.
+
+```python
+>>> def thing(stuff):
+...     return stuff * 2
+...
+>>> help(thing)
+Help on function thing in module __main__:
+
+thing(stuff)
+>>>
+```
+
+That sucked! We have no idea about what it does based on this. All we
+know is that it takes a `thing` argument.
+
+This is when documentation strings or docstrings come in. All we need to
+do is to add a string to the beginning of our function and it will show
+up in `help(the_function)`. Like this:
+
+```python
+>>> def thing(stuff):
+...     "hello there"
+...     return stuff * 2
+...
+>>> help(thing)
+Help on function thing in module __main__:
+
+thing(stuff)
+    hello there
+```
+
+Note that docstrings are not comments. If you add a `# comment` to the
+beginning of the function it won't show up in `help()`.
+
+## Multi-line strings
+
+When we did `help(print)`, we got more than one line of help. Maybe we
+could do that in our own docstring too?
+
+```python
+>>> def thing():
+...     "This thing does stuff.\n\nIt always returns None."
+...
+>>> help(thing)
+Help on function thing in module __main__:
+
+thing()
+    This thing does stuff.
+
+    It always returns None.
+>>>
+```
+
+That's better, but how what if we want to do 5 lines of prints? Our
+`"stuff\n\nstuff\nstuff"` thing would be really long and hard to work
+with. But Python has multi-line strings too. They work like this:
+
+```python
+>>> """bla bla bla
+...
+... bla bla
+... bla bla bla"""
+'bla bla bla\n\nbla bla\nbla bla bla'
+>>>
+```
+
+So we can write documented functions like this:
+
+```python
+>>> def thing():
+...     """This thing does stuff.
+...
+...     It always returns None.
+...     """
+...
+>>> help(thing)
+Help on function thing in module __main__:
+
+thing()
+    This thing does stuff.
+
+    It always returns None.
+
+>>>
+```
+
+It's recommended to always use `"""strings like this"""` for docstrings,
+even if the docstring is only one line long. This way it's easy to add
+more stuff to it later.
+
+## Documenting other stuff
+
+Docstrings aren't actually limited to functions. You can use them for
+documenting [classes](classes.md) and their methods too. For example,
+let's make a file like this and save it to `test.py`:
+
+```python
+"""A test module.
+
+It contains a class and a function.
+"""
+
+
+class Thing:
+    """This is a test class."""
+
+    def thingy(self):
+        """This is a test method."""
+        print("hello")
+
+
+def do_hello():
+    """This is a test function."""
+    thing = Thing()
+    thing.thingy()
+```
+
+Then we can import it and call help on it:
+
+```python
+>>> import test
+>>> help(test)
+Help on module testie:
+
+NAME
+    testie - A test module.
+
+DESCRIPTION
+    It contains a class and a function.
+
+CLASSES
+    builtins.object
+        Thing
+
+    class Thing(builtins.object)
+     |  This is a test class.
+     |
+     |  Methods defined here:
+     |
+     |  thingy(self)
+     |      This is a test method.
+     |
+     |  ----------------------------------------------------------------------
+     |  Data descriptors defined here:
+     |
+     |  __dict__
+     |      dictionary for instance variables (if defined)
+     |
+     |  __weakref__
+     |      list of weak references to the object (if defined)
+
+FUNCTIONS
+    do_hello()
+        This is a test function.
+
+FILE
+    /home/akuli/testie.py
+```
+
+That's pretty cool. We just added docstrings to our code and Python made
+this thing out of it.
+
+You might be wondering what `__weakref__` is. You don't need to care
+about it, and I think it would be better if `help()` would hide it.
+
+## When should we use docstrings?
+
+Always use docstrings when writing code that other people will import.
+The `help()` function is awesome, so it's important to make sure it's
+actually helpful.
+
+If your code is not meant to be imported, docstrings are usually a good
+idea anyway. Other people reading your code will understand what it's
+doing without having to read through all of the code.
+
+## Summary
+
+- `help()` is awesome.
+- A `"""triple-quoted string"""` string in the beginning of a function,
+  class or file is a docstring. It shows up in `help()`.
+- Docstrings are not comments.
+- Usually it's a good idea to add docstrings everywhere
+
+***
+
+If you have trouble with this tutorial please [tell me about
+it](../contact-me.md) and I'll make this tutorial better. If you
+like this tutorial, please [give it a
+star](../README.md#how-can-i-thank-you-for-writing-and-sharing-this-tutorial).
+
+You may use this tutorial freely at your own risk. See
+[LICENSE](../LICENSE).
+
+[Previous](classes.md) | [Next](../advanced/datatypes.md) |
+[List of contents](../README.md#basics)