Python Jumpstart by Building 10 Apps Transcripts
Chapter: App 4: Journal app and file I/O
Lecture: Documenting the journal module with docstrings
Login or
purchase this course
to watch this video and the rest of the course contents.
0:00
Let's make our journal module just a little nicer to work with. So if I come over here and I look at this journal and I hit F1,
0:07
you'll see that PyCharm can kind of guess hey I think this is returning a list but it's all that we really get.
0:15
Now, if I look at some built in like print it will give me decent documentation like hey here is all the values, here is how you typically use it,
0:24
here is a link to the documentation and so on. We would like our journal code to look like that and it turns out it's super easy.
0:31
So if we come over here and we enter a string, on its own line right by itself here, that will actually be the documentation
0:42
and there is a format that lets you describe the return values and the parameters and expectations and everything.
0:48
So, one way that we can create the string, let's just take a break for a minute, call it S is we saw we could put single quotes like this,
0:57
or we could put double quotes like this, but the third way is to extend that to be sort of a string literal across multiple lines
1:06
I could say S = ' ' ' and hit enter, right, this is multi line and close it off like that, and that's actually a string with one, two new lines
1:20
and then this and then a new line, so you can have this sort of richer strings in that way
1:26
and that is the style we are going to use, to document this here. So we are going to come over here and say ' ' ' and when I hit enter,
1:33
PyCharm is actually going to help me out. Notice it says, ok it looks like you are trying to add a docstring,
1:38
so we are going to have a parameter called name and we'll give you a chance to describe that so this will be the base name of the journal, to load,
1:48
and it can talk about the return value a new journal data structure populated with the file data, something like this and then at the top
2:01
we have the general method summary and so this method loads and say creates and loads a new journal.
2:11
So let's go over to our program and do that little trick again we had, so I can come over here and I can look at this,
2:18
and hit F1 and now it pulls it up and says this method creates and loads journal and guess what
2:23
the name parameter, this is the base name of the journal and the return value that's a new journal, Woho!!. So now you have proper documentation.
2:31
Now if we come here to Python console and we say import journal, I can write things like help (journal.load) and when I hit enter
2:40
you can see just like we got into UI there we also get the text version so if you are working in the console or the terminal
2:46
the sort of standard help also uses the same docstrings. Now I did notice that PyCharm was suggesting that we should use 3 double quotes,
2:56
so let's go and make it happy, and do that here like so, perfect. Now, of course in the real app we go right this for save
3:03
and all the other pieces, we can even do this for the module itself say this is the journal module,
3:11
and now if I were to come down here and do that import again or come over here to the top and look at the journal,
3:18
I can ask for help and it actually gives me module level documentation as well.