1 00:00:05,300 --> 00:00:08,230 In the last video, I mentioned that we should write documentation 2 00:01:26,940 --> 00:01:30,580 Alright, so let's start by having a look at some of the documentation for the built-in 3 00:01:30,580 --> 00:01:34,740 functions. We're going to start by opening the guessinggame.py file 4 00:01:34,740 --> 00:01:39,900 that we modified, when we added the get integer function to it. 5 00:01:43,300 --> 00:01:48,020 First thing I'll do is delete this code down here, starting on line 32, 6 00:01:48,020 --> 00:01:50,900 because we don't need it anymore. 7 00:01:51,270 --> 00:01:55,510 IntelliJ and PyCharm have a way to call up the documentation, while you're 8 00:01:55,510 --> 00:02:01,700 editing your code. So if you go back up to line six and we click on input, 9 00:02:01,700 --> 00:02:08,120 then use Ctrl-Q. On a Mac that's Ctrl-J, so Ctrl Q for me. And by the way, you can 10 00:02:08,120 --> 00:02:11,720 also go to the View menu and choose Quick Documentation. Now we'll see where 11 00:02:11,720 --> 00:02:16,300 this text is coming from in a moment. It starts, though, with the function signature 12 00:02:16,300 --> 00:02:21,480 showing the parameter that we provide. The type of prompt is listed as Any. 13 00:02:21,480 --> 00:02:25,420 That's true because you can pass the list as the prompt to the input function 14 00:02:25,420 --> 00:02:30,380 if you wanted to. Usually you pass a string - that's the most useful way to let 15 00:02:30,380 --> 00:02:33,500 the user know that what they should be inputting. But the documentation should 16 00:02:33,500 --> 00:02:38,000 precisely describe the function parameters, and input can accept anything 17 00:02:38,000 --> 00:02:43,070 that can be printed. In Python, that means anything. At the end of the first line, we 18 00:02:43,070 --> 00:02:47,390 get the return type of the function. So after the right arrow, we can see that 19 00:02:47,390 --> 00:02:51,710 input returns a string. We already knew that, and that's why we have to convert 20 00:02:51,710 --> 00:02:56,780 strings to integers using the int function, if we want a number. After the 21 00:02:56,780 --> 00:03:01,190 function signature, there's a description for what the function does. Alright, so 22 00:03:01,190 --> 00:03:04,160 it's time to see where all that came from. Have a quick read of this text. 23 00:03:04,160 --> 00:03:09,160 Don't try to memorize it - we just need to recognize it when we see it again. 24 00:03:09,160 --> 00:03:12,640 Now we can jump to the source code for the input function, by holding down the 25 00:03:12,650 --> 00:03:17,060 control key and clicking on input. Using a Mac, use the command key instead. 26 00:03:17,060 --> 00:03:21,170 So I'll do that now. Now that's taken us to the definition of 27 00:03:21,170 --> 00:03:25,819 the input function, in the builtins module. The editor tab says builtins.py, 28 00:03:25,819 --> 00:03:30,769 as you can see. The input function is built into Python. The text after the 29 00:03:30,769 --> 00:03:34,840 function definition should look familiar. That's what we were just looking at. 30 00:03:34,840 --> 00:03:39,440 All that text between the opening and closing triple quotes is a doc string. 31 00:03:39,440 --> 00:03:43,640 It's used to generate the documentation for functions, and lots of other things too, 32 00:03:43,640 --> 00:03:47,989 such as modules and classes. We'll look at those later. So we've just seen two 33 00:03:47,989 --> 00:03:53,480 quick ways to view the documentation for a Python object. We can use Ctrl-Q, or we 34 00:03:53,480 --> 00:03:57,109 can control click to read the doc string in the source code. As you can see, the 35 00:03:57,109 --> 00:04:00,919 documentation was created from this doc string. When we document our functions, 36 00:04:00,919 --> 00:04:05,090 we'll do that by adding a doc string to the start of the function, just like 37 00:04:05,090 --> 00:04:11,569 we've got here, on lines 248 through 256. Before I talk about doc strings in more 38 00:04:11,569 --> 00:04:16,640 detail, I'll clear up some confusion that this source code may be creating. 39 00:04:16,640 --> 00:04:21,320 The first thing you may find strange, is that there's no code in this function. It just 40 00:04:21,320 --> 00:04:25,970 contains the pass statement, as you can see on line 257. It doesn't take you long to see 41 00:04:25,970 --> 00:04:29,960 that most of the functions in this builtins module are the same. The reason 42 00:04:29,960 --> 00:04:34,260 for that is most of the things built into CPython are written in C, and 43 00:04:34,260 --> 00:04:38,980 that's why this implementation of Python is called CPython. The second thing is 44 00:04:38,980 --> 00:04:42,680 for students who have programmed in languages like C++ or Java, 45 00:04:42,680 --> 00:04:45,756 and is about the convention for placing docstrings. 46 00:04:45,756 --> 00:04:51,360 Notice that the function docstrings are inside the function definition. 47 00:05:23,240 --> 00:05:27,020 Alright, so we've now seen an example of a Docstring, and know where to put them. In the 48 00:05:27,020 --> 00:05:30,980 next video, we'll start to write our own. Before moving on to that video, 49 00:05:30,980 --> 00:05:36,000 read through PEP 257, which describes the conventions for Docstrings. 50 00:05:36,000 --> 00:05:39,040 I'll load that up on the screen now. 51 00:05:39,880 --> 00:05:44,140 Now it's not very long, and you can skip part of it. You can skip the Handling 52 00:05:44,140 --> 00:05:48,160 Docstring Indentation section. The remainder of the PEP will give you an 53 00:05:48,160 --> 00:05:52,600 idea of what should go in your Docstrings and how to lay them out. Now I'm 54 00:05:52,600 --> 00:05:56,440 going to teach Docstrings by example. We'll be adding Docstrings to most 55 00:05:56,440 --> 00:06:01,240 other functions we create, and you'll learn what we think makes for good documentation. 56 00:06:01,240 --> 00:06:04,300 See you in the next video.